WhatsApp webhooks in production: duplicates, ordering, retries and timeouts
This guide covers the problems WhatsApp webhooks cause in production and how to handle each one. It's about the webhooks Meta sends for the WhatsApp Business Platform (Cloud API). What Meta sends and how it's signed is on the WhatsApp webhooks overview, every webhook field is on WhatsApp webhook events, and signature verification code is on Verify WhatsApp webhooks.
At a glance
| Problem | What to do | With Event Gateway |
|---|---|---|
| Timeouts | Return a 200 fast; process in a background job | Accepts the delivery at once, then queues it for your service |
| Duplicates | Key messages on id, and statuses on id and status | Drops exact repeats within a window of up to an hour |
| Ordering | Only move a status forward; treat read as proof of delivery | Logs every event and attempt, so you can see arrival order when debugging |
| Retries | Store every payload; alert on failures | Accepts deliveries while your service is down and replays them |
| Choosing fields | Subscribe only to what you process; check the app's subscription | Filters and routes events by type |
| Testing | Answer the GET handshake; check Live mode | Forwards to localhost and replays past events |
| Other limits | Plan for batches, 3 MB payloads and 3x your outgoing traffic | Absorbs bursts in its queue and delivers at a rate you set |
WhatsApp webhook timeouts and slow handlers
Return a 200 as fast as you can, then do the work in a background job. Meta publishes a latency standard rather than a timeout.
Why it happens: Meta doesn't publish a timeout for webhook requests. Its throughput guidance says it attempts to deliver webhooks concurrently, and asks you to load test for a median latency of no more than 250ms, with less than 1% of requests above 1s. A handler that writes to several tables, calls an LLM or sends a reply before responding won't meet that. Meta also treats any status other than 200 as a failed delivery, so a 202 or 204 from a queueing handler gets retried too.
Fix it in your handler:
- Verify the signature and return a
200straight away. - Push the payload onto a queue and process it in a worker. See why to process webhooks asynchronously.
- Keep the request path free of Cloud API calls, including replies and media downloads.
- Load test with concurrent requests, because that's how Meta delivers.
With Event Gateway: Hookdeck accepts each delivery, then queues events and delivers them to your service at a rate it can handle, with its own retries. Your handler can take as long as it needs without failing a delivery from Meta.
Duplicate WhatsApp webhooks
Meta can deliver the same update more than once. Deduplicate each incoming message on its id, and each status on its id and status together.
Why it happens: Any failed delivery is retried, and Meta sends retries to all apps subscribed to the Messaging account, so another app's failure can give you a duplicate. The key needs care because a status webhook's id is the id of your message. Each outgoing message can have up to three status webhooks, for sent, delivered and read, and they all carry that one id. Deduplicating on id alone keeps the first and discards the real updates that follow.
Fix it in your handler:
- Walk
entry[].changes[].value, because one POST can hold several updates, and run the check on each item. - Use
messages[].idas the key for incoming messages, andstatuses[].idwithstatuses[].statusfor statuses. - Keep the keys for at least 7 days, the length of Meta's retry window. A shorter expiry lets a late retry through.
- Make every handler idempotent for the other fields, where Meta documents no delivery id.
With Event Gateway: Hookdeck deduplicates events within a window of up to an hour. Use exact deduplication, which compares the whole payload, so that different statuses for one message aren't treated as repeats. Retries that arrive after the window still reach your handler, so keep the checks above.
Out-of-order WhatsApp webhooks
Meta's docs don't promise an order and it delivers webhooks concurrently, so treat a message's status as something that only moves forward.
Why it happens: Concurrent delivery and retries both mean a newer update can reach you before an older one. Statuses also don't always form a full sequence. Meta's status reference says that when a user receives a message while in the chat screen, it's delivered and read at the same time, and the delivered webhook isn't sent. A state machine that waits for delivered before accepting read gets stuck.
Fix it in your handler:
- Rank statuses as
sent,delivered, thenread, and ignore an update that ranks below the one you have. - Treat
readas proof of delivery. Meta says a status is read only if it has been delivered. - Sort a conversation's messages by their
timestamp, not by when they arrived. It's in Unix seconds, so two messages can share a value. - For the
historyfield, usechunk_orderto put chunks back in sequence, because Meta says they may not be delivered sequentially.
With Event Gateway: Hookdeck logs every event and delivery attempt, so you can see the order things arrived in when you're debugging. Your handler still needs the rules above.
WhatsApp webhook retries and lost events
Meta retries a failed delivery for up to 7 days, then drops it, and you can't fetch it again. Keep your own copy of every payload.
Why it happens: If a delivery fails, Meta retries immediately, then a few more times with decreasing frequency over the next 7 days. After that, unacknowledged webhooks are dropped. Meta says there are no APIs for fetching historical webhook data, and the contents of a message from a user only reach you by webhook, so a bug that throws payloads away loses them for good. Meta's docs don't describe disabling an endpoint after repeated failures.
Fix it in your handler:
- Write the raw payload to durable storage before you process it, so you can replay from your own copy.
- Monitor your endpoint and alert on failures, because Meta's webhook docs describe no delivery log or failure notification.
- Leave headroom for a backlog. Retries arrive on top of live traffic when you come back from an outage.
- After an outage, read anything with a current state from the API, such as a phone number's throughput level.
With Event Gateway: Hookdeck accepts deliveries while your service is down and stores them, then retries on a schedule you control. Failed events stay available, so you can replay them one at a time or in bulk once a fix is out. See dead-letter queues for webhook reliability.
Choosing which WhatsApp webhook fields to subscribe to
Subscribe only to the fields you process, then confirm your app is subscribed to the Messaging account, because the two are separate steps.
Why it happens: Fields are chosen in the App Dashboard, but for solution providers Meta says you must subscribe to every Messaging account individually. If that subscription is missing, your URL can be verified and your fields selected while nothing arrives. Fields also vary a lot in volume: messages carries everything users send you plus up to three statuses for each message you send.
Fix it in your handler:
- Start with
messages. Addmessage_if you send templates, because a disabled template breaks outbound flows, andtemplate_ status_ update account_updateandphone_if you watch account health.number_ quality_ update - Branch on
field, then on whethervalueholdsmessagesorstatuses. - Check the subscription with
GET /<WABA_, and subscribe with a POST to the same path. Add that check to your deployment checks.ID>/subscribed_ apps - Grant the right permission:
whatsapp_forbusiness_ messaging messagesandcalls, andwhatsapp_for the other fields.business_ management - If you use callback overrides, expect template and account-level webhooks to keep going to your app's default URL.
With Event Gateway: Hookdeck filters and routes events by type, so each of your services gets only what it handles.
Testing and debugging WhatsApp webhooks
Meta needs a public HTTPS URL and a passing GET handshake before it sends anything, so test the handshake and the POST as two separate things.
Why it happens: Whenever you set or edit the Callback URL or Verify token, Meta sends a GET with hub.mode, hub.challenge and hub.verify_token. If your endpoint returns anything other than a 200 with the hub.challenge value, Meta considers it unverified and sends no webhooks, so there's no failed delivery to look at. Certificates must be valid, and self-signed ones aren't supported.
Test it:
- Serve GET and POST on the same URL, and return the
hub.challengevalue only when the verify token matches. - Expose localhost through a tunnel such as ngrok or Cloudflare Tunnel, or deploy to a staging server. A new URL means editing the Callback URL, and that sends the handshake again.
- Send a test payload from the Configuration panel, or use Meta's test webhook endpoint. If that endpoint logs payloads and yours doesn't, the problem is in your code.
- Switch your app to Live mode before you decide webhooks aren't arriving. Meta says some aren't sent in Dev mode.
With Event Gateway: Hookdeck gives you a public URL that doesn't change, and the Hookdeck CLI forwards events to your local server. You can inspect events in the dashboard and replay them against localhost without triggering new ones from WhatsApp.
Other WhatsApp webhook limits
Batches. Meta can aggregate updates into one POST with up to 1000 updates, but it doesn't guarantee batching, so handle both a single update and many.
Payload size. Payloads can be up to 3 MB. Check any body size limit in your framework or proxy.
Capacity. Meta says your servers should withstand 3x your outgoing message traffic and 1x your expected incoming traffic. Sending 1,000 messages per second with a 30% response rate means up to 3,000 status webhooks and 300 incoming message webhooks per second.
Throughput. A business phone number supports 80 messages per second by default, counting inbound and outbound, and can be upgraded automatically to 1,000. Going over returns error 130429. Numbers shared with the WhatsApp Business app are fixed at 20. A phone_ webhook reports a change in throughput level.
Pair rate limit. You can send one message every 6 seconds to the same user. Going over returns error 131056, which a chatbot replying to a burst of messages can hit.
Access tokens. Replies and media downloads need an access token, which isn't the app secret that signs webhooks. Meta tells direct developers to use a System User access token.
Securing the connection. Webhooks support mutual TLS. Meta publishes its IP ranges through a whois query, but it changes them periodically and suggests mTLS over an allowlist.
With Event Gateway: Hookdeck absorbs bursts of status webhooks in its queue and delivers them at a rate you configure, and logs every request and response so you have the delivery history Meta's docs don't describe.
Keep a long outage from losing your WhatsApp messages.
Hookdeck Event Gateway accepts each WhatsApp delivery, queues it and retries to your service on your schedule, and keeps a log of every attempt so you can replay what failed.