A WhatsApp webhook is the HTTPS endpoint Meta calls with a JSON payload when a customer writes to your business number, when a message you sent is sent, delivered, read or fails, and when a template changes status. On the Cloud API, setup takes four things: answer Meta's verification request, subscribe to the fields you need, subscribe your app to the WhatsApp Business Account (WABA), and check the X-Hub-Signature-256 signature on every POST before you return HTTP 200.
The hard part comes later. Meta retries for up to seven days, sends duplicates, doesn't promise order and has no API for missed events, so the receiver must store first, deduplicate and process afterwards. This guide follows Meta's references as read on 25 September 2026, on Graph API v26.0, the current version that day. Tokens, numbers and the first send are in WhatsApp Cloud API explained.
Setting up the endpoint, step by step
- Host a public HTTPS endpoint that answers GET and POST, with a valid TLS certificate; Meta refuses self-signed ones.
- Answer the verification request. When you save the Callback URL and Verify token in the App Dashboard (Use cases > Customize > Configuration; WhatsApp > Configuration on apps created before December 2025), Meta sends a GET with
hub.mode=subscribe,hub.challengeandhub.verify_token. If the token matches yours, reply 200 with the challenge as the body; otherwise send a 400-level code. - Subscribe to fields.
messagescarries incoming messages and outgoing statuses. Addmessage_template_status_updateandtemplate_category_updatefor templates,user_preferencesfor marketing opt-outs. The token needswhatsapp_business_messagingformessagesandwhatsapp_business_managementfor the rest. - Subscribe the app to each WABA with
POST https://graph.facebook.com/v26.0/<WABA_ID>/subscribed_apps. Meta requires one subscription per WABA. - Switch the app to Live. Meta notes that some webhooks are not sent in Development mode.
When the dashboard's Test button reaches your server but real customer messages never do, check steps 4 and 5 first.
A minimal receiver in Node.js
Illustrative code, not production code. Meta's own test endpoint parses the JSON and never checks the signature; don't copy that part. The HMAC covers the exact bytes Meta sent, so read the raw body before parsing.
import crypto from "node:crypto";
import express from "express";
const app = express();
const { VERIFY_TOKEN, APP_SECRET } = process.env;
app.get("/webhooks/whatsapp", (req, res) => {
const ok = req.query["hub.mode"] === "subscribe" &&
req.query["hub.verify_token"] === VERIFY_TOKEN;
if (ok) res.status(200).send(req.query["hub.challenge"]);
else res.sendStatus(403);
});
app.post("/webhooks/whatsapp", express.raw({ type: "application/json" }), async (req, res) => {
const got = Buffer.from(req.get("X-Hub-Signature-256") ?? "");
const want = Buffer.from("sha256=" +
crypto.createHmac("sha256", APP_SECRET).update(req.body).digest("hex"));
if (got.length !== want.length || !crypto.timingSafeEqual(got, want)) {
return res.sendStatus(401);
}
await saveRaw(req.body); // durable table or queue first
res.sendStatus(200); // then acknowledge
});
// Worker: applies each stored payload once
function apply(payload) {
for (const entry of payload.entry ?? []) {
for (const { field, value } of entry.changes ?? []) {
if (field === "messages") {
for (const m of value.messages ?? []) upsertOnce(`in:${m.id}`, m);
for (const s of value.statuses ?? []) upsertOnce(`st:${s.id}:${s.status}`, s);
} else if (field === "message_template_status_update") {
upsertOnce(`tpl:${value.message_template_id}:${value.event}:${entry.time}`, value);
}
}
}
}
saveRaw and upsertOnce stand for your storage: a table with a unique key, where a repeated key is ignored (INSERT … ON CONFLICT DO NOTHING in PostgreSQL).
What arrives: incoming messages
Every payload shares one envelope: object is whatsapp_business_account, entry[].id is the WABA ID and changes[].field names the field. In messages webhooks, value.metadata.phone_number_id says which of your numbers received the event. A customer's text, trimmed to value:
{
"contacts": [{ "profile": { "name": "Ana Souza" }, "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" }],
"messages": [{
"from": "5511987654321",
"from_user_id": "BR.13491208655302741918",
"id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNB",
"timestamp": "1761656400",
"type": "text",
"text": { "body": "Meu pedido 4821 já saiu?" }
}]
}
type varies (text, image, interactive, button, order, location, reaction and more), each with its own reference page, and a referral object marks chats that started from a Click to WhatsApp ad.
CRMs keyed by phone number need one change in 2026. Since early April every messages webhook carries user_id, a business-scoped user ID that starts with the country code (BR. for Brazil) and is unique to your business portfolio. If a customer adopts a WhatsApp username (Meta is rolling them out gradually in 2026), from and wa_id are left out unless that business number exchanged messages or calls with the customer's phone in the last 30 days, or the number is in Meta's contact book. Key contacts by user_id, keep the phone as an attribute, and subscribe to user_id_update, sent when that ID changes.
What arrives: statuses and template events
One outgoing message can produce three status webhooks: sent, delivered and read.
status | Meaning in Meta's reference |
|---|---|
sent | Left Meta's servers (one check mark) |
delivered | Reached the customer's device (two check marks) |
read | Displayed in an open chat (two blue check marks) |
failed | Not sent or not delivered; carries errors |
played | First play of a voice message |
Meta skips delivered when a message is read on arrival, and none of its webhook pages promises order, so store the furthest status reached. To tie statuses to your own records, send biz_opaque_callback_data with the message; it comes back in the status webhooks.
A failed status carries errors[].code, title and error_data.details. Codes common in customer messaging:
| Code | Meta's description | What to do |
|---|---|---|
| 131047 | More than 24 hours since the customer last replied | Send a template |
| 131026 | Message undeliverable (not on WhatsApp, old app, terms not accepted) | Reach the customer another way |
| 131049 | Not delivered to keep ecosystem engagement healthy | Wait at least 24 hours before resending |
| 131050 | Customer stopped your marketing messages | Don't retry; watch user_preferences |
| 131042 | Problem with the payment method | Fix billing in Meta Business Suite |
The pricing object doubles as an invoice check. Since 1 October 2026 service replies to Brazil cost R$0.0350 after 1,000 free per business number per month, and utility templates inside the 24-hour window cost R$0.0350. In status webhooks, free-tier replies carry pricing.type free_customer_service and billed ones regular, with the rate in pricing.category. The pricing object comes on the sent status and again on delivered or read, so count each message ID once; volume-tier rates are not in webhooks (use pricing_analytics). From v24.0 the conversation object is omitted outside free entry point windows, and billable will be deprecated.
Template events. message_template_status_update sends an event (APPROVED, REJECTED, PAUSED, DISABLED and others) with the template ID, name, language, category and reason; an INVALID_FORMAT rejection adds Meta's recommended fix. Stop a campaign on PAUSED or DISABLED instead of sending into errors; the message templates guide explains each status.
Retries, duplicates and security
- Retries. A non-200 answer is retried at once, then less often for up to seven days, and then dropped. No API returns past webhooks.
- Duplicates. Retries go to every app subscribed to the WABA. Deduplicate by message ID plus status.
- Batches. One POST can hold up to 1,000 updates (not guaranteed) and up to 3 MB. Loop over every entry, change, message and status.
- Speed. Meta publishes no timeout; 360dialog, which relays Meta's format, needs a 200 within 5 seconds. Acknowledge first, process from a queue.
- Sender checks. The signature comes first. Meta also offers mTLS, with a client certificate (common name
client.webhooks.fbclientcerts.com) signed by Meta's own CA, which replaced a DigiCert certificate that expired on 15 April 2026. Meta suggests mTLS over IP allowlists because its addresses change.
Different URLs per number: webhook overrides
The app's Callback URL receives everything by default. To route one WABA or number elsewhere, call POST /<WABA_ID>/subscribed_apps with override_callback_uri and verify_token, or POST /<PHONE_NUMBER_ID> with a webhook_configuration object. Meta checks the number, then the WABA, then the app; handy for a staging number or an agency with several clients. Template and account fields ignore overrides and always reach the app's URL.
Provider webhooks vs Meta's
Through a BSP or platform, your server usually talks to the provider. It receives Meta's webhooks and forwards them, in Meta's format or its own, under its own signature and retry rules:
- 360dialog passes Meta's Cloud API payloads through, per phone number or per WABA, with optional Basic auth on your URL.
- Twilio posts status callbacks per sender, Messaging Service or message, form-encoded by default and signed with
X-Twilio-Signature; Twilio says to validate with its SDK. - Sinch uses its own states (QUEUED_ON_CHANNEL, DELIVERED, READ, FAILED), signs the raw body with a nonce and timestamp, and retries on timeouts, 5xx and 429, not on other 4xx.
What each catalog card records for status events on its scored plan:
| The provider's webhooks report | Platforms |
|---|---|
| Delivered and read statuses plus failure reasons | 360dialog, Blip Platform (Plus and up), Botmaker (paid add-on), Gupshup, Infobip, Sinch, Treble, Twilio, Zenvia, WATI (Pro and Business, not Growth) |
| Statuses, no documented failure code | Poli Digital, VTEX CX Platform (Weni) |
| Failures only | SendPulse (Pro): error code and message; delivered and read through its chat messages API |
| No status event | Status by API: Kommo (Pro, Enterprise), Octadesk, respond.io, Umbler Talk (Impulso, Escala). None documented: Huggy, BotConversa |
| Not found on public pages | Blip Go, Digisac, Manychat, RD Station Conversas |
If a CRM or ERP needs delivery and read receipts pushed to it, shortlist the first row and confirm the plan you buy includes webhooks. Template-status webhooks by provider are in the templates guide; feeding events into a CRM, in the HubSpot integration guide.
What it costs to receive webhooks
Meta charges nothing for webhooks; you pay for hosting and for the messages they report. Going direct is the cheapest route to the full event stream, paid in developer time. Among providers, Gupshup and Twilio charge no monthly fee, only per message. Every platform whose scored plan has a confirmed status webhook, cheapest plan first:
| Platform | Plan | Price | Setup fee | Score |
|---|---|---|---|---|
| Twilio | Pay-as-you-go (Programmable Messaging + Studio) | No monthly fee, pay per message | No setup fee | 44.4 |
| SendPulse | Profissional (Pro), 500 subscribers | from R$95/month | No setup fee | 81.4 |
| 360dialog | WhatsApp API Regular | from €49/month | No setup fee | 41.2 |
| Poli Digital | Plano Entrada | from R$369.90/month | + from R$1,197.90 one-time setup | 52.5 |
| Gupshup | Console (Automate & Grow) | from $100/month | No setup fee | 44.9 |
| Botmaker | Standard | from R$600/month | Setup fee unclear: sources disagree | 64.6 |
| Zenvia | Specialist | from R$700/month | + R$649 one-time setup | 62.8 |
| VTEX CX Platform (Weni) | A partir de 1.000 conversas/mês | from R$1,900/month | No setup fee | 63.7 |
| Treble | Base plan (SMB) | from $399/month | Setup fee not published | 42.9 |
| Infobip | AgentOS | from $530/month | + one-time setup fee on request | 57.3 |
| Blip Platform | Super | from R$7,292/month | Setup fee not published | 64.4 |
| Sinch | Conversation API — WhatsApp channel | Enterprise: price on request | Setup fee not published | 46.8 |
Message charges come on top, at Meta's rate, marked up or bundled depending on the provider; the WhatsApp API pricing guide adds them up for a typical month.
Related guides
- WhatsApp Cloud API explained
- WhatsApp message templates guide
- WhatsApp bulk messaging on the official API
- WhatsApp payments in Brazil: Pix and links
- What a WhatsApp BSP is and how to choose one
About this guide
Written by the editorial team of WABA Index, an independent catalog of WhatsApp Business platforms for companies selling to customers in Brazil. No platform pays for its position or for a mention, and the site carries no affiliate links.
Methodology
On 25 September 2026 we read Meta's webhook, pricing and business-scoped user ID documentation and the provider pages listed in the sources. Provider capabilities come from the catalog cards; prices, Meta rates and scores come from the catalog data. Nothing was tested hands-on, and the code is illustrative, written against Graph API v26.0. Scoring is explained in the methodology.
Last updated
28 October 2026. Facts and sources were checked on 25 September 2026; prices, Meta rates and scores in the tables are read from the catalog data when the page loads.
FAQ
Why does my webhook get the dashboard test but not real messages?
Subscribe the app to the WABA with POST /<WABA_ID>/subscribed_apps, check that messages is subscribed, and switch the app to Live.
How long does Meta retry a failed webhook?
Up to seven days, with decreasing frequency. After that the event is lost; no API fetches it later.
Do webhooks cost anything?
Not from Meta. With providers it depends on the plan: Botmaker sells webhooks as an add-on, and WATI Growth and Umbler Talk Essencial have none.
Does the webhook say whether a message was charged?
Yes: pricing.type is regular for billed messages and free_customer_service for free ones, with the rate in pricing.category.