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
| Event | Fires when |
|---|---|
message.received | Someone sent you a WhatsApp message. Fires for every inbound message, including ones an auto-reply then answers. |
message.status | A message you sent changed state — sent, delivered, read or failed. Expect several of these per message. |
campaign.completed | Every 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:
| Header | Carries |
|---|---|
X-Chattil-Event | The event name, so you can route before parsing. |
X-Chattil-Delivery | A unique id for this attempt. Log it — it is what support will ask for. |
X-Chattil-Timestamp | Unix seconds, and part of what is signed. |
X-Chattil-Signature | sha256=<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.
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.