Mon-Fri 10am - 6pm
Webhook: status
Base URL for your account: https://cpaas.studio
POST
https://your-server.example/your-webhook (we call you)
A message you sent moved forward: sent, delivered, read — or failed. One per change; a status never moves backwards. error is present only for failed.
This is a request WE send to the URL you set on WhatsApp → Channels → Webhooks — verify X-CPaaS-Signature before trusting it.
Parameters
| Param | Type | Required | Notes |
|---|---|---|---|
event |
— | yes | |
channel |
— | yes | |
ref |
— | yes | |
wa_message_id |
— | yes | |
status |
— | yes | |
at |
— | yes | |
error |
— | no | Omitted when empty. |
error.code |
— | no | Omitted when empty. |
error.label |
— | no | Omitted when empty. |
error.message |
— | no | Omitted when empty. |
error.provider_code |
— | no | Omitted when empty. |
Request example
<?php
// Verify a CPaaS webhook (raw body!)
$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_CPAAS_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_CPAAS_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, getenv('CPAAS_WEBHOOK_SECRET'));
// Both checks: the HMAC proves it is ours; the 5-minute window
// (300 s, either direction) stops a captured request being replayed.
if (! hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) {
http_response_code(401); exit;
}
$event = json_decode($body, true);
http_response_code(200);
Success response (data)
{
"event": "status",
"channel": "WCH54DZ7M7M5V",
"ref": "1aB4-202610",
"wa_message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgS",
"status": "failed",
"error": {
"code": "invalid_number",
"label": "Invalid / not on WhatsApp",
"message": "This number is not a valid WhatsApp number.",
"provider_code": "131026"
},
"at": "2026-10-10T09:15:04+00:00"
}
Notes
- Opt in per number and per event type on WhatsApp → Numbers → Webhooks: a URL (https), the events to send, a timeout (seconds) and a retry count.
- Each event is one HTTPS POST with a JSON body (Content-Type: application/json). Respond with any 2xx within the timeout.
- Signing: every request carries X-CPaaS-Timestamp (unix seconds) and X-CPaaS-Signature: sha256=HMAC_SHA256(secret, "{timestamp}.{raw body}"). The secret is the signing secret you set on this number's webhook settings, or — if you set none — your account's webhook signing secret (Administration → API Keys). Recompute it over the RAW body and compare in constant time.
- Replay window — 5 minutes: ALSO reject any request whose X-CPaaS-Timestamp is more than 300 seconds away from your clock (either direction). The signature covers the timestamp, so a captured request cannot be re-dated — but it CAN be re-sent unchanged, and only the timestamp check stops that. Checking the HMAC alone is not enough. Keep your server clock NTP-synced; for strict replay protection also remember the signatures seen in the last 5 minutes and refuse a repeat.
- Retries: a non-2xx response, a timeout or a connection error is retried immediately, up to the retry count you set (0–5), then dropped. Delivery is at-least-once: make your handler idempotent on wa_message_id / ref.
- Order is not guaranteed across events. A status never moves backwards in our records, but your receiver may see "read" before "delivered" if a delivery attempt was retried — keep the highest.
- Webhooks start within a minute of saving (the opt-in is cached for 60 seconds).
Need more context? See Getting started for authentication, the response envelope, and the full error-code reference.