Make sense of WhatsApp webhook payloads in seconds

The first habit is answering fast. Meta expects your endpoint to return an HTTP 200 within a few seconds of receiving an event; if it does not, the platform retries — and keeps retrying with the same payload. Handlers that parse, write to the database and call downstream services before responding are the classic cause of duplicate messages appearing in an inbox. The robust pattern is boring and effective: validate the request, drop the raw body onto a queue, return 200 immediately, and do the real work in a background worker. Your processing time then has no bearing on whether Meta considers the delivery successful.

The second habit is treating status updates as a state machine, not a sequence. Under load, the sent, delivered and read receipts for a single message can arrive out of order — a read before the deliveredit logically follows is common. Code that assumes chronological arrival will happily downgrade a message from read back to delivered. Instead, key every update on the message's wamid — the same ID the send API returned — and only move state forward: sent → delivered → read, with failed as a terminal branch that carries an errors array explaining what went wrong. Deduplicate on wamid too, since retries mean you will eventually see the same event twice.

The third habit is verifying signatures in production. Every webhook Meta sends includes an X-Hub-Signature-256 header: an HMAC-SHA256 of the raw request body computed with your app secret. Compute the same HMAC over the exact bytes you received — before any JSON parsing or re-serialisation — and compare it to the header with a constant-time comparison. Skip this and anyone who discovers your endpoint URL can inject fabricated messages and statuses into your system. It is a few lines of code and the single most important security control a webhook consumer has.

If you build on InfiQ, the same knowledge transfers directly: InfiQ forwards webhook deliveries in the familiar entry/changes/value shape, signed with your X-INFIQ-API-KEY so you can verify authenticity the same way. The developer documentation covers endpoint setup, signature verification and retry behaviour in detail.