mcpField
S
setup-webhook

setup-webhook

github.com/bolna-aiDevelopment366 installsUpdated 3d ago
Repository

About setup-webhook

setup-webhook is a Bolna skill for configuring HTTP webhooks that deliver call status and execution data. It covers receiver setup, payload handling, duplicate delivery, and local testing.

Key features

  1. 01Configure a webhook URL for an agent
  2. 02Receive call and execution updates
  3. 03Handle payloads idempotently
  4. 04Test a local receiver

Use cases

  1. 01Store execution updates in a database
  2. 02Trigger CRM or support workflows
  3. 03Recover details after missed deliveries

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/bolna-ai/skills --skill setup-webhook

After installing, type/setup-webhookin Claude Code to confirm it loaded.

Bundled filesscripts/webhook_receiver.py

Details

From the project README

Setup Bolna Webhooks

What Bolna sends

Bolna sends HTTP POST requests to the configured webhook URL as call status and execution data changes. Treat the webhook payload as the execution object; use get-executions for the same execution ID to reconcile missed or duplicate delivery.

Where to configure

  • Dashboard: agent Analytics tab, "Push all execution data to webhook".
  • API: set agent_config.webhook_url when creating or patching an agent.

API patch

curl --request PATCH \
  --url "https://api.bolna.ai/v2/agent/$AGENT_ID" \
  --header "Authorization: Bearer $BOLNA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_config": {
      "webhook_url": "https://example.com/bolna/webhook"
    }
  }'

Receiver requirements

  • Public HTTPS URL in production.
  • Accept POST JSON.
  • Respond quickly with 2xx.
  • Store by execution_id or id idempotently.
  • Verify the payload shape before triggering irreversible downstream actions.
  • If firewalling, check current Bolna docs for webhook source IPs before allow-listing.

Local test receiver

python3 setup-webhook/scripts/webhook_receiver.py --port 8080

Expose with a tunnel such as ngrok or Cloudflare Tunnel, then configure the public HTTPS URL in Bolna.

Minimal payload handling pattern

  1. Parse JSON.
  2. Extract execution ID, status, agent ID, phone numbers, transcript, recording URL, and extracted data.
  3. Upsert into your database by execution ID.
  4. Trigger automation only after relevant terminal statuses, usually completed, failed, no-answer, busy, or error.
  5. If payload is incomplete, call GET /executions/{execution_id}.

Common automations

  • Send summary and recording to CRM.
  • Update lead status from extracted data.
  • Create a support ticket after failed handoff.
  • Send WhatsApp, SMS, or email through Make, Zapier, n8n, or custom code.
  • Build live dashboard cards from queued, ringing, in-progress, and completed.

Source IP to whitelist

Bolna delivers webhooks from a single source IP:

13.203.39.153

Add this to your server's firewall allow-list. Reject anything else if your endpoint is sensitive.

Payload shape

The webhook body is identical to GET /executions/{execution_id}. See https://raw.githubusercontent.com/bolna-ai/skills/main/references/execution-payload.md for the full field list, and https://raw.githubusercontent.com/bolna-ai/skills/main/references/call-statuses.md for the order in which statuses fire.

Idempotency

The same execution can produce multiple webhook deliveries as status transitions (scheduled → queued → in-progress → completed). Dedupe by (execution_id, status) — never by execution_id alone, or you'll discard later updates.

See also

  • https://raw.githubusercontent.com/bolna-ai/skills/main/references/execution-payload.md — every field in the payload.
  • https://raw.githubusercontent.com/bolna-ai/skills/main/references/call-statuses.md — status order, terminal-status filter.
  • get-executions — pull historical data for executions where the webhook failed.
  • debug-bolna-calls — diagnose missed deliveries.

Comments

Markdown supported