# WhatsApp webhooks in production: duplicates, ordering, retries and timeouts

Agent skill: `npx skills add hookdeck/webhook-skills --skill whatsapp-webhooks` ([details](https://hookdeck.com/webhooks/whatsapp/skill))

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](/webhooks/whatsapp) overview, every webhook field is on [WhatsApp webhook events](/webhooks/whatsapp/events), and signature verification code is on [Verify WhatsApp webhooks](/webhooks/whatsapp/verify).

## At a glance

| Problem | What to do | With Event Gateway |
| --- | --- | --- |
| [Timeouts](#timeouts) | Return a `200` fast; process in a background job | Accepts the delivery at once, then queues it for your service |
| [Duplicates](#duplicates) | Key messages on `id`, and statuses on `id` and `status` | Drops exact repeats within a window of up to an hour |
| [Ordering](#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](#retries) | Store every payload; alert on failures | Accepts deliveries while your service is down and replays them |
| [Choosing fields](#choosing-events) | Subscribe only to what you process; check the app's subscription | Filters and routes events by type |
| [Testing](#testing) | Answer the GET handshake; check Live mode | Forwards to localhost and replays past events |
| [Other limits](#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 {#timeouts}

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](https://developers.facebook.com/documentation/business-messaging/whatsapp/throughput#webhooks) 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview#webhook-delivery-failure) as a failed delivery, so a `202` or `204` from a queueing handler gets retried too.

**Fix it in your handler:**

1. Verify the signature and return a `200` straight away.
2. Push the payload onto a queue and process it in a worker. See [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).
3. Keep the request path free of Cloud API calls, including replies and media downloads.
4. 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 {#duplicates}

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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview#webhook-delivery-failure), 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages), 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:**

1. Walk `entry[].changes[].value`, because one POST can hold several updates, and run the check on each item.
2. Use `messages[].id` as the key for incoming messages, and `statuses[].id` with `statuses[].status` for statuses.
3. Keep the keys for at least 7 days, the length of Meta's retry window. A shorter expiry lets a late retry through.
4. Make every handler [idempotent](/webhooks/guides/implement-webhook-idempotency) for the other fields, where Meta documents no delivery id.

**With Event Gateway:** Hookdeck [deduplicates](/docs/deduplication) 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 {#ordering}

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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status) 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:**

1. Rank statuses as `sent`, `delivered`, then `read`, and ignore an update that ranks below the one you have.
2. Treat `read` as proof of delivery. Meta says a status is read only if it has been delivered.
3. 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.
4. For the `history` field, use `chunk_order` to 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 {#retries}

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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint#batching) 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform), 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:**

1. Write the raw payload to durable storage before you process it, so you can replay from your own copy.
2. Monitor your endpoint and alert on failures, because Meta's webhook docs describe no delivery log or failure notification.
3. Leave headroom for a backlog. Retries arrive on top of live traffic when you come back from an outage.
4. 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](/docs/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](/webhooks/guides/dead-letter-queues-webhook-reliability).

## Choosing which WhatsApp webhook fields to subscribe to {#choosing-events}

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](https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/manage-webhooks). 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:**

1. Start with `messages`. Add `message_template_status_update` if you send templates, because a disabled template breaks outbound flows, and `account_update` and `phone_number_quality_update` if you watch account health.
2. Branch on `field`, then on whether `value` holds `messages` or `statuses`.
3. Check the subscription with `GET /<WABA_ID>/subscribed_apps`, and subscribe with a POST to the same path. Add that check to your deployment checks.
4. Grant the right permission: `whatsapp_business_messaging` for `messages` and `calls`, and `whatsapp_business_management` for the other fields.
5. If you use [callback overrides](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/override), 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 {#testing}

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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint#get-requests) 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:**

1. Serve GET and POST on the same URL, and return the `hub.challenge` value only when the verify token matches.
2. 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.
3. Send a test payload from the Configuration panel, or use [Meta's test webhook endpoint](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/set-up-whatsapp-echo-bot). If that endpoint logs payloads and yours doesn't, the problem is in your code.
4. 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](/docs/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 {#other-limits}

**Batches.** Meta can aggregate updates into [one POST with up to 1000 updates](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint#batching), 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/throughput#webhooks) 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_number_quality_update` webhook reports a change in throughput level.

**Pair rate limit.** You can send [one message every 6 seconds](https://developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform) 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens).

**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.