By QuickMessage Team · Last updated November 3, 2026
Quick answer
WhatsApp webhooks are HTTP POST requests that the WhatsApp Business Platform sends to your server when something happens: a customer sends a message, or a message you sent changes status (sent, delivered, read or failed). Your endpoint must reply with HTTP 200; if it does not, Meta retries with decreasing frequency for up to 7 days, so your code must handle duplicate notifications. Payloads can be up to 3 MB.
Webhooks are how your software learns what is happening on WhatsApp without asking every few seconds. This guide explains how they work, what you receive and how to build an endpoint that is reliable.
What webhooks tell you
| Event | Use it to |
|---|---|
| Incoming message | Save the message, start a chatbot flow or create a support ticket |
| Button reply | Confirm or cancel an order, book a slot, record a choice |
| Status: sent / delivered / read | Update your records and reports |
| Status: failed | Read the error code and retry, fix data or switch to another channel. See error codes |
How an incoming message looks
In Meta's payload, messages arrive inside entry[].changes[].value.messages[]. A simplified example:
{
"entry": [{
"changes": [{
"field": "messages",
"value": {
"messages": [{
"from": "919876543210",
"id": "wamid.XXXX",
"timestamp": "1762156800",
"type": "text",
"text": { "body": "Hi, is my order shipped?" }
}]
}
}]
}]
}Status updates for messages you sent arrive in a statuses array in the same structure, with the message ID, the new status and, for failures, an error code.
Building a reliable webhook endpoint
- Use HTTPS with a valid certificate.
- Reply 200 quickly. Save the payload to a queue and process it afterwards, so slow work does not cause retries.
- Handle duplicates. Retries can deliver the same event more than once; use the message ID to ignore repeats.
- Do not rely on order. A "read" status can arrive before "delivered"; keep the most advanced status.
- Verify the sender. Check the signature header Meta sends with each request, or use mutual TLS, which Meta supports and recommends over IP allowlisting because Meta's IP addresses change.
- Log and monitor failures, so you notice if your endpoint stops responding.
Source: Meta's WhatsApp webhooks overview.
Webhooks with QuickMessage
If you use QuickMessage, you do not need to set up Meta's webhooks yourself. QuickMessage receives WhatsApp events for your number, shows them in the dashboard and shared team inbox, and can forward them to your own system through QuickMessage webhooks. Your developers can send messages with our REST API. Ask our team for the API documentation during onboarding.
Frequently asked questions
What is a WhatsApp webhook?
It is an HTTP request the WhatsApp Business Platform sends to your server when a customer messages you or when a message you sent changes status.
What happens if my webhook endpoint is down?
Meta retries the notification with decreasing frequency for up to 7 days until your endpoint returns HTTP 200. Retries can create duplicates, so handle them using the message ID.
How big can a WhatsApp webhook payload be?
Meta says webhook payloads can be up to 3 MB.
Connect WhatsApp to your software
Talk to our team about QuickMessage's REST API and webhooks for your use case.
Book a free demo