How WhatsApp Webhooks Actually Work

Sending on WhatsApp is the easy half. A successful POST to Meta means only that your message was accepted for delivery - it says nothing about whether it arrived, whether anyone read it, or whether the recipient replied. All of that comes back to you later, as HTTP callbacks to an endpoint you host.

Webhooks are where most WhatsApp integrations quietly go wrong, because they mostly work in development and then behave differently under real load.

Registration: the handshake nobody remembers

Before Meta sends you anything, it verifies you own the endpoint. It issues a GET request with three query parameters: hub.mode, hub.verify_token and hub.challenge.

Your job is to check that hub.verify_token matches the token you configured, then respond 200 with the raw value of hub.challenge as the entire body. Not wrapped in JSON. Not with a trailing newline your framework helpfully added. The raw string.

Verification failing silently is the single most common reason a new integration receives nothing at all. Meta will not retry it on a schedule and there is no alert - the endpoint simply never becomes active.

The payload is nested deeper than you expect

Once active, Meta POSTs JSON. Everything of value sits four levels down, and every level is an array.

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "<WABA_ID>",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "918828210065",
          "phone_number_id": "<PHONE_NUMBER_ID>"
        },
        "statuses": [{
          "id": "wamid.HBgMOTE...",
          "status": "delivered",
          "timestamp": "1757318400",
          "recipient_id": "919876543210"
        }]
      }
    }]
  }]
}

Two fields inside value matter. messages carries inbound messages from people. statuses carries updates on messages you sent. A single POST can contain several of either, and it can contain both.

Write the parser defensively. entry and changes are arrays even when they almost always have one element, and code that indexes [0] will drop events the day Meta batches two together. That day arrives during your busiest hour, not your quietest.

Verify the signature, and verify it against the raw body

Every POST carries an X-Hub-Signature-256 header: an HMAC SHA-256 of the request body, keyed with your app secret, prefixed sha256=. Your endpoint is a public URL that accepts JSON and mutates your data. Verify it.

The detail that costs people an afternoon: it must be the raw bytes as received. Most web frameworks parse JSON before your handler runs, and if you re-serialise that parsed object to compute the hash, key ordering and whitespace will differ from what Meta signed. The signature will never match and the error tells you nothing useful. Capture the raw body before parsing.

If you run more than one Meta app against a single endpoint, note that each app signs with its own secret. A setup that only knows the primary secret will reject every callback from the second app as unauthorised - which looks, from the outside, exactly like a broken integration rather than a configuration gap.

Acknowledge fast, process later

This is the piece of advice that gets ignored until it causes an outage, so here is ours.

Meta expects a prompt 200. If your handler does real work first - writing rows, resolving a guest, firing a notification - you are holding the connection open while Meta waits. Meta does not wait indefinitely. It abandons the request and retries.

We learned the shape of this the expensive way. Our API ran a small pool of synchronous workers, and a burst of inbound replies arrived faster than they drained. Response times climbed past twenty seconds, at which point Meta began abandoning callbacks mid-request - and then retrying them. The retries joined the same queue as the originals. A traffic spike that should have caused slowness instead caused a compounding backlog and an outage that lasted thirteen minutes.

The fix is architectural, not a tuning parameter. Validate the signature, push the payload onto a queue, return 200. Do the actual work in a background worker. A webhook handler should be one of the least interesting pieces of code you own.

At least once, not exactly once

Because Meta retries, you will receive duplicates. Not occasionally - routinely, whenever the network hiccups or your server takes a moment too long.

Deduplicate on the WhatsApp message id, the wamid. string. It is stable across retries. Anything that has a side effect - sending a reply, deducting a credit, notifying a human - must be idempotent against it, or your users will get double replies during exactly the incidents where they are already unhappy.

Ordering is not guaranteed either

A message’s status normally progresses sent → delivered → read. The callbacks announcing those transitions do not reliably arrive in that order. Receiving delivered before sent is unremarkable.

So never let an arriving status blindly overwrite the stored one. Compare the payload’s timestamp, or rank the statuses and only ever move forward. Systems that write whatever arrived last will show messages flipping back from read to sent, and nobody will trust the dashboard again.

Absence of an event is not evidence of failure

The most common misreading of webhook data is treating a missing read status as a problem. If the recipient has read receipts disabled, that event will never exist - the message was read, and you will simply never know.

Design the user-facing language accordingly. “Delivered” is a fact. “Read” is a fact. “Not read” is an assumption, and presenting it as a failure generates support conversations you cannot resolve. We spell out how we present this distinction to non-technical users in our delivery tracking write-up.

A short checklist

• Echo hub.challenge raw, and confirm the endpoint actually went active
• Subscribe the business account to the fields you need, not just the app
• Capture the raw body before parsing, and verify X-Hub-Signature-256
• Return 200 in milliseconds; queue the work
• Deduplicate on wamid.
• Order statuses by payload timestamp, never by arrival
• Alert on a drop in webhook volume, not only on errors - silence is the failure mode that hides

That last one is worth more than the rest combined. A webhook integration rarely fails loudly. It stops receiving, everything looks calm, and you find out from a customer three days later.