Webhook documentation
WhatsApp Business API Webhook Integration
A WhatsApp Business API webhook is the callback URL to which Meta’s WhatsApp Business Platform sends incoming customer messages and status updates (sent, delivered, read and failed) for messages from your business number.
Updated
How Meta’s webhook architecture works
On the WhatsApp Business Platform, webhooks are configured on a Meta app. The app is subscribed to a WhatsApp Business Account (WABA), and to the webhook fields it needs. When something happens on a business phone number in that account, Meta sends an HTTPS POST to the app’s callback URL.
Who owns that callback URL depends on your setup. If you manage your own Meta app, Meta calls your server directly. If your WhatsApp access is provided through TXTPro, events may be received by the platform and then forwarded to you. Which model applies is confirmed during onboarding.
Incoming customer messages
When a customer writes to your business number, the webhook contains the message with a type such as text, image, document, audio, location, contacts or an interactive reply, plus the sender’s WhatsApp ID and a timestamp. Media arrives as a media ID that must be downloaded separately through the API.
An incoming message also opens or refreshes the customer service window during which you can reply freely; outside it, Meta requires an approved template. See WhatsApp Business API for how templates work.
Message status updates
| Status | Meaning |
|---|---|
| sent | Meta accepted the message and sent it towards the recipient. |
| delivered | The message reached the recipient’s device. |
| read | The recipient opened the message. |
| failed | The message could not be delivered; the update includes error details. |
Status updates reference the WhatsApp message ID (beginning wamid.) returned when you sent the message. Store it to correlate updates.
Delivered and read receipts
Delivered and read updates arrive as separate events. Customers can turn off read receipts in their privacy settings, in which case you may see delivered but never read. Report read rate as a minimum, and do not resend a message just because no read event arrived.
Failed message events
A failed status includes an error object with a code and title. Common causes include messaging a customer outside the service window without a template, using a template that is paused or not approved, or a recipient who cannot receive the message. Store the error code and look it up in Meta’s error reference rather than guessing; codes and meanings are maintained by Meta and change over time.
Interactive replies
When a customer taps a reply button or chooses an item from a list message, the incoming message carries the ID you assigned to that button or row, along with its title. Quick-reply buttons on templates arrive as button replies with their payload. Use the IDs, not the visible titles, to decide what happens next, because titles can be translated or edited.
Webhook verification
When a callback URL is registered with Meta, Meta sends a GET request with hub.mode=subscribe, hub.verify_token and hub.challenge. Your endpoint must confirm the verify token matches the value you configured and respond with the challenge value. Meta requires the callback URL to use HTTPS with a valid certificate.
// WhatsApp Cloud API (Meta) endpoint verification and payload signature check.
// Meta sends a GET request when you register the callback URL, and signs each
// POST with X-Hub-Signature-256 using your Meta app secret.
import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.get('/webhooks/whatsapp', (req, res) => {
const ok = req.query['hub.mode'] === 'subscribe' && req.query['hub.verify_token'] === process.env.META_VERIFY_TOKEN;
return ok ? res.status(200).send(req.query['hub.challenge']) : res.sendStatus(403);
});
app.post('/webhooks/whatsapp', express.raw({ type: 'application/json', limit: '256kb' }), (req, res) => {
const header = req.get('X-Hub-Signature-256') ?? '';
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.META_APP_SECRET).update(req.body).digest('hex');
const valid = header.length === expected.length && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
if (!valid) return res.sendStatus(401);
// Queue JSON.parse(req.body) for asynchronous processing, then acknowledge.
return res.sendStatus(200);
});
Security considerations
- The verify token only protects the registration handshake. Authenticate every POST by checking the
X-Hub-Signature-256header, an HMAC-SHA256 of the raw body computed with your Meta app secret. - Compute the signature over the raw bytes before parsing JSON, and compare it in constant time.
- Keep the app secret and verify token in a secrets manager; never in client-side code.
- Incoming messages contain personal data and free text. Mask phone numbers in logs and never log message bodies.
These are Meta’s mechanisms for direct integrations. If events reach you through TXTPro, the authentication used for forwarded events is confirmed during onboarding. See the webhook security guide.
Event subscriptions
In Meta’s model, incoming messages and message status updates are delivered through the messages webhook field. Meta offers other fields for account-level changes, such as template status updates. Subscriptions only take effect once the app is subscribed to the WhatsApp Business Account.
Native Meta payloads vs a TXTPro-normalised format
A native Meta webhook wraps each update in entry and changes arrays, with statuses or messages nested inside value. The abbreviated example below follows the structure in Meta’s public documentation, with placeholders instead of real identifiers:
{
"object": "whatsapp_business_account",
"entry": [{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "<BUSINESS_NUMBER>", "phone_number_id": "<PHONE_NUMBER_ID>" },
"statuses": [{
"id": "wamid.<MESSAGE_ID>",
"status": "read",
"timestamp": "1731062140",
"recipient_id": "<CUSTOMER_NUMBER>"
}]
}
}]
}]
}If your account receives events through TXTPro in a normalised format, a status update could instead look like a flat event shared with your other channels, as in this illustration:
{
"event_id": "evt_example_003",
"event_type": "message.read",
"message_id": "msg_example_789",
"channel": "whatsapp",
"status": "READ",
"timestamp": "2026-11-08T10:35:40Z"
}In the normalised illustration, message_id would map to the wamid of the original message, timestamp would be an ISO 8601 time rather than Meta’s Unix seconds, and event_id would be a unique notification ID added for deduplication, which Meta’s native status object does not provide.
Troubleshooting WhatsApp webhooks
| Symptom | What to check |
|---|---|
| Callback URL will not verify | The verify token matches exactly and the response body is the raw challenge value |
| Verification succeeds but no events arrive | The app is subscribed to the WhatsApp Business Account and to the messages field |
| Signature checks fail | Verify against the raw body and the correct app secret, before any JSON parsing |
| Read status never appears | The customer may have disabled read receipts |
| Duplicate updates | Respond with 200 quickly and deduplicate on message ID plus status |
Official reference: WhatsApp Business Platform documentation.
Frequently asked questions
How does WhatsApp webhook verification work?
Meta sends a GET request containing hub.mode, hub.verify_token and hub.challenge. Your endpoint checks the verify token and returns the challenge. After that, each POST should be authenticated with the X-Hub-Signature-256 header.
Why am I not receiving read statuses from WhatsApp?
Customers can turn off read receipts, so some delivered messages never produce a read update.
Will I receive Meta’s native webhook payloads through TXTPro?
It depends on how your WhatsApp account is set up. Whether you receive native Meta payloads or a normalised format is confirmed during onboarding.
Which webhook field carries incoming WhatsApp messages?
In Meta’s model, incoming messages and status updates are delivered through the messages field of the WhatsApp Business Account subscription.
