WhatsApp Cloud API webhook not working? A step-by-step checklist
Meta's WhatsApp webhook won't verify, or verifies but sends nothing? Work through six checks in order (verify token, public HTTPS, subscribed field, overrides, signature, 200 reply) with a tested Node receiver and curl commands.
November 18, 2026 · 10 min read
You saved the callback URL in the Meta App Dashboard, and either it refuses to verify, or it says "verified" and then no messages ever arrive. Both are common, and they have different causes. This guide goes through six checks in the order Meta's requests actually hit your server, with a small receiver you can run and test with curl before you point Meta at it.
SendFromChat is an independent product and is not affiliated with Meta or WhatsApp. This guide is about Meta's own webhook for the WhatsApp Cloud API. The Meta behaviour below comes from Meta's developer documentation, read on 18 Nov 2026 (see Sources). We read the pages through a fetch tool that summarises them, and we have not reproduced every failure on a live Meta app, so check anything critical against the linked page.
What was tested. The receiver below was run locally on Node v24 and exercised with curl: right verify token (200 and the challenge back), wrong token (403), correctly signed POST (200), tampered body (401), missing signature header (401). It was not run against Meta's servers or a live WhatsApp number.
The short version
- Verification is a GET. Your URL must answer
hub.mode=subscribewith thehub.challengevalue, status 200, whenhub.verify_tokenmatches what you typed in the dashboard. - Your URL must be public HTTPS with a valid certificate. Self-signed certificates are not supported.
- Verified is not subscribed. You also have to subscribe to the
messagesfield, and an app in Dev mode may not get some webhooks. - An override can win over your dashboard URL. A callback set on the phone number or the WhatsApp Business Account takes precedence over the app's.
- The signature uses your App Secret, not your verify token, and it is computed over the raw body.
- Answer 200 fast, and expect repeats. Do the work after you reply.
Which stage is failing?
| What you see | Stage | Go to |
|---|---|---|
| The dashboard refuses to save the callback URL (it reports a validation error) | Verification (GET) | Check 1, then 2 |
| Saved fine, but nothing arrives when someone writes to the number | Subscription or routing | Check 3, then 4 |
| Requests arrive, your code rejects them | Signature | Check 5 |
| Requests arrive and are accepted, but the same message shows up twice | Delivery semantics | Check 6 |
Before anything else, put one log line at the very top of your handler that prints the method, path and query string. If that line never prints when you click Verify and save, the request is not reaching your code (Checks 2 and 4). If it prints, the problem is in your response (Check 1).
Check 1: the verification request
When you save the callback URL, Meta sends a GET to it with three query parameters: hub.mode (set to subscribe), hub.verify_token (the string you typed in the dashboard) and hub.challenge. Your endpoint has to compare the token and, if it matches, respond with the challenge value. Meta's Graph API webhooks page describes this exchange.
The usual ways it fails:
- The tokens differ. A trailing space, a different environment on the server, or a token you changed in one place only. Print what you received next to what you expect.
- You reply with JSON or HTML instead of the bare challenge. Return the challenge on its own, as plain text, with status 200. A framework that wraps the value in
{ "challenge": … }or an HTML page fails the check. - The route only accepts POST. Many frameworks register one handler per method. Verification needs a GET handler on the same path you entered in the dashboard.
- The URL redirects or asks for a login. An auth middleware, a
wwwto non-wwwredirect, or a staging password page will all break it. Request the exact URL withcurl -iand look at the status line.
Test it yourself before involving Meta:
curl -i "https://YOUR-HOST/webhook?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=1158201444"
You want HTTP/1.1 200 and a body of exactly 1158201444. With a wrong token you want a 403 and no challenge.
Check 2: URL and TLS
Meta's documentation says the endpoint must have a valid TLS or SSL certificate and that self-signed certificates are not supported. Practical consequences:
http://URLs andlocalhostdo not work. While developing, use a tunnel that gives you a real HTTPS hostname, and re-enter the URL in the dashboard whenever the tunnel hostname changes.- Check the whole certificate chain, not just the browser lock.
curl -v https://YOUR-HOST/webhookfails on an incomplete chain or an expired certificate, and prints which. - A firewall, IP allow-list or bot protection in front of the route can block Meta's servers. If your host logs show nothing at all during Verify and save, look there first.
Check 3: subscribed field, Live mode and the test payload
A verified URL only proves your server can answer the handshake. Meta sends nothing until you subscribe to fields:
- In the App Dashboard, open WhatsApp > Configuration (for apps created with use cases: Use cases > Customize > Configuration) and subscribe to
messages. Without it you get neither incoming messages nor status updates. - Meta's webhook guide says the
messagesfield needs thewhatsapp_business_messagingpermission. - Check the app mode. Meta notes that some webhooks are not sent while an app is in Dev mode, so if everything else looks right, switch the app to Live mode.
- Use the test-payload option in the Configuration panel (the exact label may differ). It sends a sample payload to your URL, so you can see your signature check and parsing run without needing a real message. If the test arrives and real messages do not, suspect the subscription, the mode or an override (Check 4), not your code.
Check 4: callback overrides
Meta lets you override the callback URL per WhatsApp Business Account or per phone number. The documented precedence is: phone number first, then the WhatsApp Business Account, then the app's callback. So you can fix the URL in the dashboard and still receive nothing, because an older override sits above it.
Look at what is set on the account (use a current Graph API version from Meta's docs for GRAPH_VERSION):
curl -s "https://graph.facebook.com/GRAPH_VERSION/WABA_ID/subscribed_apps" \
-H "Authorization: Bearer ACCESS_TOKEN"
An override_callback_uri in the response means that URL is receiving the account's events. Meta's override page documents how to set one (a POST to /WABA_ID/subscribed_apps with override_callback_uri and verify_token) and says that subscribing again without a body removes the account-level override. Phone-number-level overrides are covered on the same page. Changing overrides on a production number affects live traffic, so write down the existing value first.
If you use a provider or a tech partner, they may have set an override on your account. Ask before you remove one.
Check 5: the signature
Notifications carry an X-Hub-Signature-256 header. Meta's docs describe it as a SHA256 signature of the payload made with your App Secret (App Dashboard > App settings > Basic), and say you don't have to validate it but should. Three mistakes break it:
- Using the verify token as the key. They are different values. The verify token is a string you made up for the GET handshake. The App Secret is issued by Meta.
- Hashing parsed JSON. Compute the HMAC over the raw bytes of the request body. If your framework parses and re-serialises the body first, key order and whitespace change and the hashes no longer match. Read the raw body, verify, then parse.
- Comparing with
==. Use a constant-time comparison, and check lengths first, becausetimingSafeEqualthrows on buffers of different length.
Here is a complete receiver with verification, signature check and an immediate 200. It needs Node 18 or newer and has no dependencies.
// webhook.mjs: a minimal Meta WhatsApp Cloud API webhook receiver (Node 18+, no dependencies)
import http from "node:http";
import crypto from "node:crypto";
const VERIFY_TOKEN = process.env.VERIFY_TOKEN; // the string you typed in the App Dashboard
const APP_SECRET = process.env.APP_SECRET; // App Dashboard > App settings > Basic
function validSignature(rawBody, header) {
if (!header?.startsWith("sha256=")) return false;
const expected = crypto.createHmac("sha256", APP_SECRET).update(rawBody).digest("hex");
const got = header.slice("sha256=".length);
return got.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}
http.createServer((req, res) => {
const url = new URL(req.url, "http://localhost");
if (url.pathname !== "/webhook") { res.writeHead(404).end(); return; }
// 1. Verification: Meta sends a GET when you save the callback URL.
if (req.method === "GET") {
const ok =
url.searchParams.get("hub.mode") === "subscribe" &&
url.searchParams.get("hub.verify_token") === VERIFY_TOKEN;
console.log("verify request:", ok ? "accepted" : "rejected");
// Reply with the challenge only, as plain text, status 200.
if (ok) res.writeHead(200, { "Content-Type": "text/plain" }).end(url.searchParams.get("hub.challenge"));
else res.writeHead(403).end();
return;
}
// 2. Event notifications: a POST with a JSON body, signed with your App Secret.
if (req.method === "POST") {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks);
if (!validSignature(raw, req.headers["x-hub-signature-256"])) {
console.log("POST rejected: bad or missing signature");
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // acknowledge first, work afterwards
const body = JSON.parse(raw.toString("utf8"));
for (const entry of body.entry ?? [])
for (const change of entry.changes ?? []) {
const v = change.value ?? {};
console.log(change.field, "messages:", v.messages?.length ?? 0, "statuses:", v.statuses?.length ?? 0);
}
});
return;
}
res.writeHead(405).end();
}).listen(3000, () => console.log("listening on :3000"));
Run it and try every case:
export VERIFY_TOKEN=my-verify-token APP_SECRET=testsecret
node webhook.mjs > server.log 2>&1 &
PID=$!; sleep 1
echo "--- A: verify, right token"; curl -s -i "http://localhost:3000/webhook?hub.mode=subscribe&hub.verify_token=my-verify-token&hub.challenge=1158201444" | sed -n '1p;$p'
echo "--- B: verify, wrong token"; curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:3000/webhook?hub.mode=subscribe&hub.verify_token=nope&hub.challenge=1"
BODY='{"object":"whatsapp_business_account","entry":[{"id":"1","changes":[{"field":"messages","value":{"messages":[{"from":"4915112345678","type":"text"}]}}]}]}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$APP_SECRET" | sed 's/^.* //')
echo "--- C: signed POST"; curl -s -o /dev/null -w "%{http_code}\n" localhost:3000/webhook -H "X-Hub-Signature-256: sha256=$SIG" -d "$BODY"
echo "--- D: tampered body"; curl -s -o /dev/null -w "%{http_code}\n" localhost:3000/webhook -H "X-Hub-Signature-256: sha256=$SIG" -d "${BODY/4915/4916}"
echo "--- E: no header"; curl -s -o /dev/null -w "%{http_code}\n" localhost:3000/webhook -d "$BODY"
sleep 1; kill $PID; echo "--- server log"; cat server.log
Expected: 200 plus the challenge for the right token, 403 for the wrong one, 200 for the signed POST, 401 for the tampered body and for the missing header.
Check 6: reply 200 first, and expect duplicates
Meta's documentation says to respond with 200 OK to each notification. If you don't, Meta retries. The handler above acknowledges first and works afterwards, so a slow database call cannot turn into a failed delivery.
Two things to design for:
- The same event can arrive more than once. Meta says to handle duplicates. Store the message ID (
messages[].id, or for statuses the message ID plus the status) and skip what you have already processed. - Order and batching are not guaranteed. One POST can hold several changes, and Meta's docs say batching can't be guaranteed. Loop over
entry[].changes[]as the example does, and never assume one message per request.
On how long Meta keeps retrying, Meta's own pages disagree: the general Graph API webhooks page says retries continue with decreasing frequency for up to 36 hours, while the WhatsApp webhook setup page says up to 7 days. We have not tested which applies to your account. Treat delivery as at-least-once, and if you were down for a day or more, do not assume the backlog will be replayed. For anything that matters, compare against your sent-message records or poll the message status as a fallback.
If you would rather not run this endpoint
Everything above is the cost of owning the direct webhook: a public endpoint, signature handling, retry behaviour and the override and subscription state in Meta's dashboard. That is a reasonable choice if you want full control, and our comparison with the Cloud API direct says what you give up and what you keep.
With SendFromChat, Meta's webhook points at us, and your app gets our own events (message.received, message.status, contact.opted_out) in a signed request in a different format: a SendFromChat-Signature header (t=…,v1=…), a 2xx answer expected within 5 seconds, retries with backoff for about a day, and deliveries that can repeat. You still run an HTTPS endpoint and still handle duplicates, but you no longer manage Meta's verify handshake or subscriptions. The details are in our REST API reference and the guide to receiving WhatsApp replies with a signed webhook.
Related reading: delivery statuses explained, Cloud API error codes, setting up the Cloud API and the 24-hour window.
A note for EU and UK customers
SendFromChat stores data in Mumbai, India. Transfers from the EU and UK are covered by the Standard Contractual Clauses and the UK Addendum in our Data Processing Agreement, and the sub-processors are listed publicly. Customer messages that reach your endpoint become data in your own systems too, so read our GDPR guide for consent, opt-out and records. This is not legal advice.
Try it
Start the 30-day free trial (no card), connect a number, create a test key and register an endpoint, or keep your own Meta app and use the checklist above.
Sources
All Meta pages read on 18 Nov 2026 through a fetch tool that summarises pages. QA spot-checked them on 18 Nov with the same kind of fetch tool, not against the primary text.
- Meta, Webhooks: getting started: verification request,
X-Hub-Signature-256, TLS requirement, 200 response, retries, duplicates, batching. - Meta, Set up webhooks for the WhatsApp Business Platform: subscribing to fields, Live mode note, test payload, retries, payload size.
- Meta, Webhook overrides: precedence and
override_callback_uri. - Meta, WhatsApp Business Account
subscribed_appsreference: listing subscribed apps. - SendFromChat REST API reference, webhook section: our event names, signature header, 5-second answer, retries.
Do this from your AI assistant
SendFromChat connects Claude, ChatGPT, Cursor or any MCP client to the WhatsApp Business API — templates, bulk sends, inbox, chatbots and sequences, just by asking. 30 days free, no card.
Start freeMore guides
How to handle WhatsApp STOP and opt-outs in your app
A customer replied STOP on WhatsApp. What must your app do? Honour the opt-out everywhere, block the next send, log it, and let people opt back in, with a tested webhook handler and the exact error to expect.
Retry WhatsApp API sends without double-sending: idempotency keys, timeouts and 429s
How to retry a failed WhatsApp send safely. An Idempotency-Key example in Node, what the API does on a replay, a timeout, a 409 or a 429, and which errors you should never retry. Tested against a local mock.
Send a WhatsApp message with cURL: copy-paste commands
Send a WhatsApp template message from the command line with cURL. Check your key, send with a test key first, retry without double-sending, read the status, and a short shell script that handles the errors.
WhatsApp template variables: how to fill the parameters from the API (and why a send says missing_variables)
How to fill {{1}}, {{2}} and {{3}} in a WhatsApp template from code, with curl and Node examples, a check that counts the values before you send, and what the 132000 and 132012 errors mean when a send does reach Meta.