The messages webhook

What the payload carries

One or more messages in a single delivery, each with the sender, an id and a type. The type decides which other keys are present.

• The sender's phone number, and the phone number id of the number they wrote to.
• A wamid message id, which is what deduplication is built on.
• A unix timestamp.
• A type: text, image, audio, video, document, sticker, location, contacts, reaction, button or interactive.
• For media types, a media id to fetch with rather than the bytes themselves.

Why it never reaches us on a routed number

Because the override moves this field, along with smb_message_echoes, to whatever destination you nominate.\n\nMeta lets an app override where a WhatsApp Business Account delivers its webhooks. We set that override to your URL, which takes the message path off our infrastructure entirely. There is no copy, no queue and no retention on our side, because the delivery never arrives there.\n\nWhen no destination is set, these events fall back to our default callback, where the handler drops them without persisting. That is the difference between a claim about storage and a code path: there is nowhere for conversation content to go.

Acknowledging correctly

Return 200 before you do the work, not after.\n\nMeta treats a slow response as a failure and retries, which means a handler that processes inline will see the same message more than once. Respond immediately, put the payload on a queue or a background task, and let the work happen outside the request.\n\nOn serverless this is not optional. A function that returns and then keeps working may be frozen the moment it responds, so the acknowledgement and the processing have to be genuinely separate.

Deduplicating

On the wamid, always, because retries are normal rather than exceptional.\n\nThe same message can arrive twice for reasons that have nothing to do with a bug on your side: a slow response, a network timeout, a deploy landing mid delivery. Storing seen ids and skipping repeats is a few lines and it is the difference between a customer being answered once and being answered twice.\n\nOn a Coexistence number this matters more, because smb_message_echoes arrives on the same path and a handler that treats every event as new will reply on top of a human who already answered.

Common mistakes

• Processing before returning 200. Meta retries a slow response and you handle the message twice.
• Skipping deduplication. Retries are by design, not an edge case.
• Expecting media bytes in the payload. It carries a media id to fetch with.

Frequently asked questions

Keep reading