Browse the docsWebhooks

Developers

Webhooks

Chattil POSTs to your URL when something happens, so you do not have to poll for it. Add an endpoint under Developers in the dashboard.

Events

EventFires when
message.receivedSomeone sent you a WhatsApp message. Fires for every inbound message, including ones an auto-reply then answers.
message.statusA message you sent changed state — sent, delivered, read or failed. Expect several of these per message.
campaign.completedEvery recipient of a campaign has been attempted. The payload carries the final per-status counts.

An endpoint with no events selected receives all of them. Subscribing to only what you handle is cheaper for both sides.

The request

Every delivery carries these headers:

HeaderCarries
X-Chattil-EventThe event name, so you can route before parsing.
X-Chattil-DeliveryA unique id for this attempt. Log it — it is what support will ask for.
X-Chattil-TimestampUnix seconds, and part of what is signed.
X-Chattil-Signaturesha256=<hex>. See below.
{
  "event": "message.received",
  "timestamp": "2026-08-01T14:22:05Z",
  "data": {
    "from": "+233201234567",
    "text": "Are you open on Sunday?",
    "message_id": "3EB0…",
    "conversation_id": 41
  }
}

Verifying the signature

The signature is HMAC-SHA256 over <timestamp>.<raw body>, keyed with the endpoint secret shown when you created it. Sign the raw bytes: parsing the JSON and re-serialising it changes the whitespace and the signature will not match.

Compare in constant time — hmac.compare_digest, not ==. A plain comparison returns faster on an earlier mismatch, which is enough to recover a valid signature one byte at a time. Reject anything whose timestamp is more than a few minutes old, so a captured request cannot be replayed.
import hashlib, hmac, time

def verify(secret: str, request) -> bool:
    ts  = request.headers.get("X-Chattil-Timestamp", "")
    sig = request.headers.get("X-Chattil-Signature", "")
    body = request.get_data()          # raw bytes, before any parsing

    if abs(time.time() - int(ts)) > 300:      # stale: refuse a replay
        return False

    expected = "sha256=" + hmac.new(
        secret.encode(), f"{ts}.".encode() + body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig)

Retries and ordering

Answer 2xx quickly — acknowledge first, do the work after. A non-2xx is retried with backoff, and an endpoint that keeps failing is disabled automatically and shown as such in the dashboard rather than being retried forever.

Events are not guaranteed to arrive in order, and a delivery may arrive more than once. Each carries a timestamp and the message id, which is enough to reconstruct the sequence and to make your handler idempotent.

Next