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

Webhook: optout

API Documentation / WhatsApp / Webhook: optout

Base URL for your account: https://cpaas.studio

POST https://your-server.example/your-webhook (we call you)

A contact opted out: replied STOP / UNSUBSCRIBE (source keyword), or was added on the opt-out page (manual_optout) or through the API (api_optout). scope is marketing or all.

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
from — yes
scope — yes
source — yes
at — yes

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": "optout",
    "channel": "WCH54DZ7M7M5V",
    "from": "919876543210",
    "scope": "marketing",
    "source": "keyword",
    "at": "2026-10-10T09:16:00+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.