Log inStart Free Trial
Meta Tech Provider

WhatsApp webhook retries, duplicates and order: how to handle them

Meta retries a WhatsApp webhook that gets anything other than HTTP 200, immediately and then with decreasing frequency for up to 7 days, and drops it after that. Retries go to every app subscribed to the account, so duplicates are normal. Answer 200 fast, deduplicate on the message id or on status id plus status, and order events by their own timestamps.

easyCoexistence connects your WhatsApp Business app number to Meta's Cloud API through Coexistence and absorbs Meta's redeliveries before your automations see them, so a retried message does not get a second AI reply.

7 days

How long Meta keeps retrying a webhook that did not get HTTP 200, before dropping it.

1,000

Most updates Meta batches into one POST; Meta does not promise batching, so handle each request on its own.

3 MB

Largest payload a WhatsApp webhook POST can carry.

7 days

How long easyCoexistence remembers each incoming message id, so a redelivered message does not run an automation twice.

7 attempts

Tries per forward to your Forward URL, each waiting 10 seconds for a 2xx, over about 33 hours.

When does Meta retry a WhatsApp webhook?

Whenever a delivery to your endpoint gets an HTTP status other than 200, or cannot be delivered at all. Meta retries immediately, then a few more times with decreasing frequency over the next 7 days, and drops what is still unacknowledged after that. The retries go to every app subscribed to the WhatsApp Business Account for that field, which is why Meta warns they can produce duplicate notifications. There is no API to fetch past webhooks, so a delivery that runs out its 7 days is lost to your system.

Why do duplicates arrive even when your server is healthy?

Because a delivery can succeed on your side and still look failed to Meta. A handler that does its work before answering can run past Meta's wait, so Meta retries something you already processed. A deploy that restarts the server mid-request, a load balancer returning 502 for a moment, or a 201 or 204 instead of 200 all count as failures. Batches add one more case: one POST can hold many updates, so a timeout on a large batch brings the whole batch back, including the updates you handled.

Which key should you deduplicate on?

Meta's own ids, chosen per event type, because one message legitimately produces several webhooks. A status key without the status value would drop delivered and read as copies of sent, and a call key without the event would keep only the first stage of a call. Store the keys with a unique index, so two workers handling the same retry cannot both win:

messages[].idIncoming messages: the wamid.
statuses[].id + statusOne message has sent, delivered, read; each is its own event.
message_echoes[].idReplies the owner typed in the WhatsApp Business app.
calls[].id + eventA call's connect, statuses and terminate share the wacid.
user id + value + timestampuser_preferences: a customer can stop and resume more than once.

In what order do webhooks arrive?

Not necessarily the order things happened. Meta's documentation makes no ordering promise, a retried delivery lands after newer ones, and a status can skip a step: Meta sends read without delivered when a message is read the moment it arrives. So store events with their own timestamp field, compare a status by rank rather than by arrival, and let a later customer message win over an earlier one that came in late. On a Coexistence number the one-time history import can overlap with live messages around onboarding, and the message id is what reconciles the two.

What does a safe handler look like?

Four moves: verify, answer exactly 200, deduplicate, then work from a queue, so nothing slow sits between Meta's request and your response. This version checks X-Hub-Signature-256 with your own Meta app's secret; for a number connected through easyCoexistence, Meta signs with easyCoexistence's app secret, so a direct destination authenticates with a long secret in its URL path instead, or switches to managed forwarding signed per number.

meta-webhook.mjs: 200 first, then deduplicate (Node.js, no dependencies)
// meta-webhook.mjs: node meta-webhook.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";

const APP_SECRET = process.env.META_APP_SECRET; // the secret of the Meta app that subscribed
const seen = new Set(); // keys already accepted: a unique index in a database in production

// One key per thing that happened, so a redelivery maps to the same keys.
function keysOf(field, value) {
  const keys = [];
  for (const m of value.messages ?? []) keys.push(`${field}:msg:${m.id}`);
  for (const s of value.statuses ?? []) keys.push(`${field}:status:${s.id}:${s.status}`);
  for (const e of value.message_echoes ?? []) keys.push(`${field}:echo:${e.id}`);
  for (const c of value.calls ?? []) keys.push(`${field}:call:${c.id}:${c.event}`);
  return keys;
}

http.createServer((req, res) => {
  const chunks = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", () => {
    const raw = Buffer.concat(chunks);
    const got = Buffer.from(String(req.headers["x-hub-signature-256"] ?? ""));
    const want = Buffer.from("sha256=" + crypto.createHmac("sha256", APP_SECRET).update(raw).digest("hex"));
    if (req.method !== "POST" || got.length !== want.length || !crypto.timingSafeEqual(got, want)) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(200).end(); // exactly 200, before any work
    const body = JSON.parse(raw.toString("utf8"));
    for (const entry of body.entry ?? []) {
      for (const change of entry.changes ?? []) {
        for (const key of keysOf(change.field, change.value ?? {})) {
          if (seen.has(key)) continue; // a retry of something already accepted
          seen.add(key);
          // queue { key, field: change.field, value: change.value } for a worker here
          console.log("new", key);
        }
      }
    }
  });
}).listen(process.env.PORT ?? 3000);

How does easyCoexistence handle retries on a connected number?

On the way in, easyCoexistence checks Meta's signature, answers 200 and runs automations after the response, so Meta does not retry because an AI reply took a few seconds. Each incoming message id is kept for 7 days, the length of Meta's retry window, and a redelivered message is recognized and does not trigger a second automation reply.

On the way out to your Forward URL, each Meta change becomes one delivery with an id in X-EC-Delivery that stays the same across forward retries: 7 attempts over about 33 hours, each waiting 10 seconds for a 2xx. A change Meta itself redelivers is forwarded again under a new delivery id, so deduplicate on Meta's ids inside value as well.

Common mistakes

  • Deduplicating statuses on id alone. sent, delivered and read share the wamid, so the key needs the status too.
  • Processing before answering. A slow handler makes Meta retry work you already did; return 200 first and work from a queue.
  • Returning 201 or 204. Meta's documentation treats any status other than 200 as a failed delivery and retries it.
  • Deduplicating forwards only on X-EC-Delivery. A change Meta redelivers arrives under a new delivery id; keep Meta's ids as the second key.
Doing this with EasyCoexistence

Forwards to your server are signed, queued and retried, and every number is monitored 24/7. US$ 9 down to US$ 0.75 per number per month, falling as you add numbers, with the first 3 days free.

easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.

Frequently asked questions

How long should I keep the ids I have seen?

At least 7 days, Meta's retry window. A delivery Meta retries on day six must still match its key, or it will be processed as new.

What happens to my customers' messages if my endpoint is down for days?

Meta retries for up to 7 days and then drops the webhooks. On a Coexistence number the conversations are still in the WhatsApp Business app on the phone, so the business can answer from there.

Can I replay webhooks I missed?

Not from Meta: there is no API for historical webhook data. The one-time history import of a Coexistence number runs only at onboarding and cannot be requested again for the same connection.

Does Meta send the same update to more than one server?

It sends to every app subscribed to the WhatsApp Business Account for that field. With a destination override, the number's message fields go to the override URL instead of that app's default callback.

Keep reading

Ready to get started?

Set up WhatsApp Coexistence in minutes, not months. The app keeps working on the phone.

Start Free Trial

Verified on