Skip to main content
flag
Mon - Fri   10:00 – 18:00

Status webhook

API Documentation / Voice Broadcast / 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).

This is a request WE send to the webhook_url you gave. Every request is signed with your account's webhook signing secret — verify X-CPaaS-Signature before trusting it (see Verifying webhook signatures).

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.