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

  1. Host a public HTTPS endpoint that answers GET and POST, with a valid TLS certificate; Meta refuses self-signed ones.
  2. 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.challenge and hub.verify_token. If the token matches yours, reply 200 with the challenge as the body; otherwise send a 400-level code.
  3. Subscribe to fields. messages carries incoming messages and outgoing statuses. Add message_template_status_update and template_category_update for templates, user_preferences for marketing opt-outs. The token needs whatsapp_business_messaging for messages and whatsapp_business_management for the rest.
  4. Subscribe the app to each WABA with POST https://graph.facebook.com/v26.0/<WABA_ID>/subscribed_apps. Meta requires one subscription per WABA.
  5. 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.

statusMeaning in Meta's reference
sentLeft Meta's servers (one check mark)
deliveredReached the customer's device (two check marks)
readDisplayed in an open chat (two blue check marks)
failedNot sent or not delivered; carries errors
playedFirst 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:

CodeMeta's descriptionWhat to do
131047More than 24 hours since the customer last repliedSend a template
131026Message undeliverable (not on WhatsApp, old app, terms not accepted)Reach the customer another way
131049Not delivered to keep ecosystem engagement healthyWait at least 24 hours before resending
131050Customer stopped your marketing messagesDon't retry; watch user_preferences
131042Problem with the payment methodFix 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 reportPlatforms
Delivered and read statuses plus failure reasons360dialog, 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 codePoli Digital, VTEX CX Platform (Weni)
Failures onlySendPulse (Pro): error code and message; delivered and read through its chat messages API
No status eventStatus by API: Kommo (Pro, Enterprise), Octadesk, respond.io, Umbler Talk (Impulso, Escala). None documented: Huggy, BotConversa
Not found on public pagesBlip 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:

PlatformPlanPriceSetup feeScore
TwilioPay-as-you-go (Programmable Messaging + Studio)No monthly fee, pay per messageNo setup fee44.4
SendPulseProfissional (Pro), 500 subscribersfrom R$95/monthNo setup fee81.4
360dialogWhatsApp API Regularfrom €49/monthNo setup fee41.2
Poli DigitalPlano Entradafrom R$369.90/month+ from R$1,197.90 one-time setup52.5
GupshupConsole (Automate & Grow)from $100/monthNo setup fee44.9
BotmakerStandardfrom R$600/monthSetup fee unclear: sources disagree64.6
ZenviaSpecialistfrom R$700/month+ R$649 one-time setup62.8
VTEX CX Platform (Weni)A partir de 1.000 conversas/mêsfrom R$1,900/monthNo setup fee63.7
TrebleBase plan (SMB)from $399/monthSetup fee not published42.9
InfobipAgentOSfrom $530/month+ one-time setup fee on request57.3
Blip PlatformSuperfrom R$7,292/monthSetup fee not published64.4
SinchConversation API — WhatsApp channelEnterprise: price on requestSetup fee not published46.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.

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.