Mon-Fri 10am - 6pm
Webhook: message
Base URL for your account: https://cpaas.studio
POST
https://your-server.example/your-webhook (we call you)
A contact sent a message to your number (text, media, button / list reply, location, …). Sent only for a message that was stored (and billed, if inbound messages are charged on your plan).
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 | |
message |
— | yes | |
message.ref |
— | yes | |
message.wa_message_id |
— | yes | |
message.type |
— | yes | |
message.received_at |
— | yes | |
message.from |
— | no | Omitted when empty. |
message.username |
— | no | Omitted when empty. |
message.profile_name |
— | no | Omitted when empty. |
message.text |
— | no | Omitted when empty. |
message.reply |
— | no | Omitted when empty. |
message.media |
— | no | Omitted when empty. |
message.media.mime_type |
— | no | Omitted when empty. |
message.media.caption |
— | no | Omitted when empty. |
message.media.filename |
— | no | Omitted when empty. |
message.context_wa_message_id |
— | no | Omitted when empty. |
message.reply.type |
— | no | Omitted when empty. |
message.reply.id |
— | no | Omitted when empty. |
message.reply.title |
— | no | Omitted when empty. |
message.reply.description |
— | 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": "message",
"channel": "WCH54DZ7M7M5V",
"message": {
"ref": "1aB3-202610",
"wa_message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAEhgUM0E",
"from": "919876543210",
"profile_name": "Asha",
"type": "text",
"text": "Is my order shipped?",
"received_at": "2026-10-10T09:15:02+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.