Mon-Fri 10am - 6pm
Status webhook
Base URL for your account: https://cpaas.studio
POST
https://your-server.example/your-webhook (we call you)
When a broadcast was sent with webhook_url (Voice Broadcast or Voice Broadcast with Text to Speech), we POST a JSON event to that URL each time one of its numbers changes status: when it is handed to the operator (submitted) and when the call result arrives (answered, no_answer, busy or failed). On Voice Broadcast, numbers rejected at submit (duplicate, invalid) are already in the submit response and get no webhook. On Voice Broadcast with Text to Speech the submit response comes before numbers are checked, so each number skipped while preparing gets one final webhook instead (no_audio, duplicate or invalid).
Parameters
| Param | Type | Required | Notes |
|---|---|---|---|
event |
string | yes | Always voice.broadcast.status. |
event_id |
string (UUID) | yes | Unique per status change; the same on every retry of that change. Also sent as the X-CPaaS-Event-Id header. De-duplicate on it. |
request_id |
string | yes | The broadcast id returned by Voice Broadcast (data.id). |
call_id |
string | yes | The per-number id (numbers[].id on Voice Broadcast and Voice Broadcast Number Status). |
number |
string | yes | The recipient number as stored (numbers[].mobile). |
status |
string | yes | submitted, answered, no_answer, busy or failed; for Text to Speech also no_audio, duplicate or invalid — the same words as Voice Broadcast Number Status. |
duration |
integer or null | yes | Call duration in seconds from the operator's call result; null on submitted. |
answered_at |
ISO-8601 or null | yes | When the call was answered; null unless status is answered. |
reference |
string or null | yes | The reference you sent with the broadcast. |
custom_param |
string or null | yes | Your webhook_param, unchanged; null if you did not send one. Useful as an extra correlation token on top of the signature. |
timestamp |
ISO-8601 | yes | When we recorded the status change (with UTC offset). |
Request example
<?php
// Your receiver: verify, answer fast, work later.
$body = file_get_contents('php://input');
if (! cpaas_signature_ok($body)) { // see Verifying webhook signatures
http_response_code(401); exit;
}
$event = json_decode($body, true);
// Retries resend the same event_id — skip ones you already have.
if (! already_processed($event['event_id'])) {
queue_for_processing($event); // e.g. update your CRM using custom_param
}
http_response_code(200);
Success response (data)
{
"event": "voice.broadcast.status",
"event_id": "0b6f1d2e-8c4a-4f7e-9a51-3c2d7e9b1f40",
"request_id": "BCQVCUU6YTAA",
"call_id": "BCQVCUU6YTAA-1",
"number": "9876543210",
"status": "answered",
"duration": 32,
"answered_at": "2026-11-09T10:15:04+00:00",
"reference": "order-4471",
"custom_param": "crm-lead-88231",
"timestamp": "2026-11-09T10:15:41+00:00"
}
Notes
- Request: POST, Content-Type: application/json, User-Agent: CPaaSStudio-Webhook/1.0, X-CPaaS-Event-Id: <event_id>, X-CPaaS-Timestamp, X-CPaaS-Signature.
- Every request is signed with your account's webhook signing secret — see Verifying webhook signatures. Each retry has a new X-CPaaS-Timestamp and so a new signature; the body and event_id stay the same.
- Respond with any 2xx within 10 seconds (5 seconds to connect). Reply first and do your own processing afterwards.
- Redirects are not followed — a 3xx counts as a failed delivery. Point webhook_url at the final address.
- Retries: a timeout, a connection error, any 5xx, 408 or 429 is retried 3 more times — after 1 minute, 5 minutes and 15 minutes — then dropped. Any other 4xx is not retried.
- Delivery is at least once and order is not guaranteed: de-duplicate on event_id, and keep a final status (answered, no_answer, busy, failed) over submitted if they arrive out of order.
- Each status is sent once per number, and nothing is sent after a final status — repeats from the operator are ignored.
- Before every attempt the address is checked again; if your host now resolves to a private or reserved address, the event is dropped.
- Sending webhooks never affects billing.
Need more context? See Getting started for authentication, the response envelope, and the full error-code reference.