Webhooks

Voicebip delivers real-time events to your webhook URL via HTTP POST with HMAC-SHA256 signatures.

Event Types

Voice

SMS & WhatsApp

Internal NATS Subjects (Not Delivered to Webhooks)

Voicebip’s internal pipelines publish additional subjects that are not forwarded to your webhook URL today. They are documented here so you can recognise them in support tickets and dashboard activity feeds, and so the boundary between “webhook events” and “internal pipeline events” is explicit.

If you have a use case for receiving any of these as webhooks, open an issue — most can be surfaced behind a feature flag.

Payload Format

Every webhook delivery is a JSON object with a common outer envelope and an event-type-specific payload field.

Envelope

1
{
2
  "event_id": "evt_abc123",
3
  "event_type": "call.completed",
4
  "channel": "voice",
5
  "agent_id": "agt_PAEZ_njcfm2kycpjs",
6
  "number": "+2349012345678",
7
  "from": "+2348031234567",
8
  "timestamp": "2026-05-23T12:34:56Z",
9
  "payload": { ... }
10
}

call.initiated

Published when a call connects and media is flowing. Phone numbers are always E.164; Nigerian DIDs use the +234 country code.

1
{
2
  "event_id": "evt_abc123",
3
  "event_type": "call.initiated",
4
  "channel": "voice",
5
  "agent_id": "agt_PAEZ_njcfm2kycpjs",
6
  "number": "+2349012345678",
7
  "from": "+2348031234567",
8
  "timestamp": "2026-05-23T12:34:00Z",
9
  "payload": {
10
    "call_id": "call_01HXYZ...",
11
    "workspace_id": "ws_xyz123",
12
    "direction": "inbound",
13
    "from_number": "+2348031234567",
14
    "to_number": "+2349012345678",
15
    "mno": "mtn"
16
  }
17
}

call.transcription

Published on every final STT transcript — once per caller utterance. The turn_id matches the turn_id field in the BYOM webhook request for the same utterance.

1
{
2
  "event_id": "evt_def456",
3
  "event_type": "call.transcription",
4
  "channel": "voice",
5
  "agent_id": "agt_PAEZ_njcfm2kycpjs",
6
  "timestamp": "2026-05-23T12:34:07Z",
7
  "payload": {
8
    "call_id": "call_01HXYZ...",
9
    "turn_id": "turn_xk9j...",
10
    "text": "I'd like to check my outstanding balance.",
11
    "is_final": true,
12
    "confidence": 0.95,
13
    "conversation_history": [
14
      { "turn_id": "turn_ab12", "role": "agent",  "text": "Hi, this is Kemi. How can I help?", "timestamp": "2026-05-23T12:34:02Z" },
15
      { "turn_id": "turn_xk9j", "role": "caller", "text": "I'd like to check my outstanding balance.", "timestamp": "2026-05-23T12:34:07Z" }
16
    ]
17
  }
18
}

call.completed

Published when the call ends. Contains the full transcript and AI-mode metadata. Check ai_mode to confirm whether the call was handled by your BYOM webhook ("byom") or a hosted provider.

1
{
2
  "event_id": "evt_ghi789",
3
  "event_type": "call.completed",
4
  "channel": "voice",
5
  "agent_id": "agt_PAEZ_njcfm2kycpjs",
6
  "timestamp": "2026-05-23T12:35:02Z",
7
  "payload": {
8
    "call_id": "call_01HXYZ...",
9
    "workspace_id": "ws_xyz123",
10
    "status": "completed",
11
    "duration_seconds": 62,
12
    "direction": "inbound",
13
    "mno_used": "mtn",
14
    "ai_mode": "byom",
15
    "recording_url": "/v1/calls/call_01HXYZ.../recording",
16
    "quality_score": 4.1,
17
    "transcript": [
18
      { "turn_id": "turn_ab12", "role": "agent",  "text": "Hi, this is Kemi. How can I help?",            "timestamp": "2026-05-23T12:34:02Z" },
19
      { "turn_id": "turn_xk9j", "role": "caller", "text": "I'd like to check my outstanding balance.",    "timestamp": "2026-05-23T12:34:07Z" },
20
      { "turn_id": "turn_mn34", "role": "agent",  "text": "Your balance is ₦45,000, due April 20th.",     "timestamp": "2026-05-23T12:34:09Z" }
21
    ]
22
  }
23
}

Signature Verification

Every webhook delivery includes the following headers:

The signed payload is "{timestamp}.{body}" — the Unix timestamp string, a literal ., then the raw request body. This lets you reject replayed deliveries by checking the timestamp age.

1
import hmac
2
import hashlib
3
import time
4
5
def verify_webhook(body: bytes, headers: dict, secret: str, max_age_seconds: int = 300) -> bool:
6
    signature = headers.get("X-Voicebip-Signature", "")
7
    timestamp = headers.get("X-Voicebip-Timestamp", "")
8
    if not timestamp:
9
        return False
10
    # Reject replays older than max_age_seconds (default 5 minutes)
11
    if abs(time.time() - int(timestamp)) > max_age_seconds:
12
        return False
13
    signed_payload = f"{timestamp}.{body.decode('utf-8')}".encode()
14
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
15
    return hmac.compare_digest(f"sha256={expected}", signature)

1
import (
2
    "crypto/hmac"
3
    "crypto/sha256"
4
    "crypto/subtle"
5
    "encoding/hex"
6
    "math"
7
    "net/http"
8
    "strconv"
9
    "time"
10
)
11
12
func verifyWebhook(r *http.Request, body []byte, secret string) bool {
13
    signature := r.Header.Get("X-Voicebip-Signature")
14
    tsStr := r.Header.Get("X-Voicebip-Timestamp")
15
    if tsStr == "" {
16
        return false
17
    }
18
    ts, err := strconv.ParseInt(tsStr, 10, 64)
19
    if err != nil {
20
        return false
21
    }
22
    // Reject replays older than 5 minutes
23
    skew := time.Since(time.Unix(ts, 0))
24
    if skew < 0 {
25
        skew = -skew
26
    }
27
    if skew > 5*time.Minute {
28
        return false
29
    }
30
    mac := hmac.New(sha256.New, []byte(secret))
31
    mac.Write([]byte(tsStr))
32
    mac.Write([]byte{'.'})
33
    mac.Write(body)
34
    expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
35
    return subtle.ConstantTimeCompare([]byte(expected), []byte(signature)) == 1
36
}

Retry Policy

Failed webhook deliveries are retried with exponential backoff:

A delivery is considered failed if your endpoint returns a non-2xx status code or times out after 10 seconds.

Testing Webhooks

POST /v1/webhooks/test delivers a realistic mock payload to any URL with a valid HMAC signature — no real call or message is needed.

$
# Simulate a call.completed event
$
curl -X POST "https://api.voicebip.com/v1/webhooks/test" \
>
  -H "Authorization: Bearer pk_live_your_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{"webhook_url": "https://your-server.com/webhook", "event_type": "call.completed"}'

The mock payload always includes:

• Valid Nigerian E.164 phone numbers (+2348031234567, +2349012345678)
• Realistic conversation history
• A valid X-Voicebip-Signature HMAC header so your verification code runs

Supported event_type values: call.initiated, call.transcription, call.completed, call.barge_in, call.idle_silence, call.quality, call.quality_degraded, message.received, message.sent, message.delivered, message.failed.

Testing BYOM Routing End-to-End

The fastest way to verify your BYOM webhook before a live call:

1. Expose a local endpoint with ngrok: ngrok http 8080
2. Update your agent’s webhook_url to the ngrok URL
3. Use a pk_test_ API key — sandbox mode synthesizes the full BYOM turn without a real SIP call or billing charge
4. Fire a call.transcription test event to your events endpoint to see what the event stream looks like alongside the BYOM turn requests:

$
curl -X POST "https://api.voicebip.com/v1/webhooks/test" \
>
  -H "Authorization: Bearer pk_test_your_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "webhook_url": "https://your-ngrok.ngrok-free.app/events",
>
    "event_type": "call.completed"
>
  }'

5. Make a sandbox test call (or use the Dashboard’s “Test call” button) and watch both channels: BYOM turn POSTs arrive at webhook_url, lifecycle events arrive at the registered events endpoint.

Signing Secret Rotation

When you rotate your workspace’s signing secret, Voicebip sends both the new and old signatures during a 24-hour grace period:

• X-Voicebip-Signature — signature using the new secret
• X-Voicebip-Signature-Previous — signature using the old secret (present during 24h grace window only)

Your verification code should accept either signature during rotation to avoid rejecting valid deliveries.

Multiple Webhook Endpoints (Fan-Out)

Each agent supports multiple webhook URLs. When a matching event fires, the platform delivers the same payload to every active endpoint independently — each has its own attempt counter, retry queue, and delivery status. One slow or failing endpoint does not affect delivery to the others.

Register an Endpoint

$
curl -X POST "https://api.voicebip.com/v1/agents/agt_PAEZ_njcfm2kycpjs/webhooks/endpoints" \
>
  -H "Authorization: Bearer pk_live_your_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "url": "https://primary.example.com/webhook",
>
    "description": "Primary handler"
>
  }'

Response:

1
{ "id": "whep_abc123def456gh78" }

List Endpoints

$
curl "https://api.voicebip.com/v1/agents/agt_PAEZ_njcfm2kycpjs/webhooks/endpoints" \
>
  -H "Authorization: Bearer pk_live_your_key"

1
{
2
  "endpoints": [
3
    {
4
      "id": "whep_abc123def456gh78",
5
      "agent_id": "agt_PAEZ_njcfm2kycpjs",
6
      "url": "https://primary.example.com/webhook",
7
      "active": true,
8
      "description": "Primary handler"
9
    },
10
    {
11
      "id": "whep_zyx987wvu654ts32",
12
      "agent_id": "agt_PAEZ_njcfm2kycpjs",
13
      "url": "https://backup.example.com/webhook",
14
      "active": true,
15
      "description": "Backup handler"
16
    }
17
  ]
18
}

Pause / Resume an Endpoint

Toggle the active flag without deleting the endpoint:

$
curl -X PATCH "https://api.voicebip.com/v1/agents/agt_PAEZ_njcfm2kycpjs/webhooks/endpoints/whep_abc123def456gh78" \
>
  -H "Authorization: Bearer pk_live_your_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{ "active": false }'

Delete an Endpoint

$
curl -X DELETE "https://api.voicebip.com/v1/agents/agt_PAEZ_njcfm2kycpjs/webhooks/endpoints/whep_abc123def456gh78" \
>
  -H "Authorization: Bearer pk_live_your_key"

Webhook Delivery Log

Monitor recent webhook deliveries via the API or the Voicebip Dashboard.

List Deliveries

$
curl "https://api.voicebip.com/v1/webhooks/deliveries?page_size=20" \
>
  -H "Authorization: Bearer pk_live_your_key"

Each delivery entry includes the event type and payload, HTTP status code from your endpoint, retry attempt count, and next retry timestamp if applicable.

Get a Single Delivery

$
curl "https://api.voicebip.com/v1/webhooks/deliveries/del_abc123" \
>
  -H "Authorization: Bearer pk_live_your_key"

Replay Failed Deliveries (DLQ)

If your endpoint was down during the retry window, you can replay failed deliveries from the dead-letter queue:

$
curl -X POST "https://api.voicebip.com/v1/webhooks/dlq/replay" \
>
  -H "Authorization: Bearer pk_live_your_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{"event_ids": ["evt_abc123", "evt_def456"]}'

Replayed deliveries restart the full 7-attempt retry sequence from attempt 1.