Glossary
What is a WhatsApp webhook and what does it send?
The callback URL where Meta delivers incoming WhatsApp messages, sent/delivered/read/failed statuses and template updates, with a sample event and common failures.
By Broadchat teamPublished 3 min read
Definition
Webhook: A webhook is an HTTPS address that Meta calls whenever something happens on a WhatsApp Business account. Meta posts a JSON event to it for every incoming customer message and for every status change of a message you sent: sent, delivered, read or failed. Template approvals and category changes arrive the same way. Without a working webhook, a business cannot see replies or delivery reports.
Also called: Callback URL, Webhook endpoint, WhatsApp webhook
How a WhatsApp webhook works
The Cloud API does not wait for you to ask whether a customer replied. Instead, the app that connects your number registers one callback URL with Meta and subscribes to the WhatsApp fields it needs. Meta first checks the URL with a verification request (a verify token and a challenge value the server must echo back). After that, each event is sent as an HTTPS POST with a JSON body.
Two kinds of event matter most:
- Messages: text, media, button taps, list selections, locations and other content a customer sends. Each carries the sender's number, a message ID and a timestamp.
- Statuses: updates for messages you sent, identified by the same message ID:
sent,delivered,readorfailed(with an error code such as 131047 when the 24-hour window had closed).
Account-level events, such as a message template moving from Pending to Approved or being recategorised, also arrive on the webhook.
Example: tracing one order message
Meera runs Rangoli Home and sends Arjun an order update at 10:02. Over the next minutes her server receives three status events for the same message ID: sent, then delivered when it reaches his phone, then read at 10:15. At 10:16 a fourth event arrives, this time a message: Arjun tapped the Track order button. Each event lands on the webhook within seconds; her system matches them by message ID and shows a single conversation.
If Meera's server had been down at 10:15, those events would not have reached her system on time. An endpoint that keeps failing is a real business risk: replies go unseen and reports stay stuck on "sent".
Common problems
| Symptom | Likely cause |
|---|---|
| No replies appear anywhere | App not subscribed to the WhatsApp Business account, or verification failed |
| Statuses stop at sent | Endpoint returning errors or timing out |
| Duplicate messages in your system | Retries not de-duplicated by message ID |
| Events for the wrong number | Several numbers share one URL and the phone number ID is ignored |
Webhooks in Broadchat
Broadchat receives Meta's webhook for every connected number, so replies show in CRM → Live Chat and campaign reports update from the statuses. If you also need the events in your own system (a CRM, an ERP, a data warehouse), each channel under Channels → All Channels can forward incoming messages and statuses to your URL. You do not register anything with Meta yourself. For the wider picture of how the platform fits together, see what the WhatsApp Business API is.
Sources
- Webhooks for the WhatsApp Cloud API — Meta for Developers, checked 12 October 2026
- Cloud API error codes — Meta for Developers, checked 12 October 2026
Broadchat team · Product and partner success team
The people who build and support Broadchat, the white-label WhatsApp Business API platform. We write from what we see while onboarding partners and their clients on the official WhatsApp Cloud API, and we check every article against Meta's current documentation.
Last updated:
Frequently asked questions
Can I use more than one webhook URL for the same number?
Meta delivers the events to the app that is subscribed to the WhatsApp Business account. If you need the same events in a second system, forward them from the first one. In Broadchat, the channel's webhook forwarding does this for you.
Does a read status always arrive?
No. A read status arrives only if the customer has read receipts turned on. Treat delivered as the reliable signal and read as a bonus.
Why did I get a failed status with code 131047?
It means you tried to send a free-form message after the 24-hour customer service window had closed. Send an approved message template instead.