Meta webhooks
Last verified against Meta's documentation on September 27, 2026.
Meta sends webhooks for WhatsApp Business, Instagram, Messenger, Facebook Pages, and more, all through one system: the Webhooks product in your app’s dashboard. Most problems come from a few places: the hub.challenge handshake that has to pass before anything is delivered, a signature check that breaks on non-English text, and an endpoint that fails long enough for Meta to unsubscribe your app. This page covers what Meta sends, how it delivers, how to fix the common errors, and where HookDeploy fits.
What Meta sends webhooks for
You subscribe to fields on an object. These are the ones developers use most.
| Product | Object | Key fields | Typical use |
|---|---|---|---|
| WhatsApp Business | whatsapp_business_account | messages, message_template_status_update | Receive customer messages and delivery statuses (sent, delivered, read, failed), track template approvals |
| Messenger | page | messages, messaging_postbacks, message_deliveries, message_reads | Run chatbots, handle button taps, track delivery and read receipts |
instagram | messages, comments, mentions | Answer DMs, moderate comments, track mentions | |
| Facebook Pages | page | feed, leadgen | React to posts and comments, push lead ads into a CRM |
Every notification is a JSON POST with an object and an entry array. WhatsApp, Instagram comments, and Page fields put their data under entry[].changes[]. Messenger and Instagram messaging put theirs under entry[].messaging[]. One request can carry several entries, so always loop.
Subscribing your app to fields isn’t enough on its own. Each WhatsApp Business Account, Page, or Instagram account also has to be connected to your app before its events are delivered.
How Meta delivers webhooks
| Behavior | Detail |
|---|---|
| Verification | A GET with hub.mode=subscribe, hub.challenge, and hub.verify_token. Your endpoint checks the token and responds with the challenge value, or the subscription isn’t created |
| Signature header | X-Hub-Signature-256, formatted sha256=<hex>: an HMAC-SHA256 keyed with your app secret |
| What gets signed | An escaped-unicode version of the payload, with lowercase hex digits. äöå is signed as \u00e4\u00f6\u00e5 |
| Legacy signature | X-Hub-Signature (SHA-1). Use the SHA-256 header |
| Timestamp in signature | None. The signature doesn’t expire |
| Success | An HTTP 200. WhatsApp and other Meta products treat any other status as a failed delivery |
| Messenger and Instagram retries | Immediately, then a few more times. After 15 minutes of failures, your developer account gets an alert. After 1 hour, you get a Webhooks Disabled alert and your app is unsubscribed from that Page or Instagram account |
| WhatsApp retries | Up to 7 days with exponential backoff, then the notification is dropped |
| WhatsApp latency targets | Median response under 250 ms, and fewer than 1% of responses over 1 second |
| Duplicates | Expected, because of retries |
| TLS | A valid certificate is required. Self-signed certificates aren’t supported |
Common Meta webhook errors and how to fix them
“The callback URL or verify token couldn’t be validated”
Meta sent the verification GET and didn’t get the right answer. Check that your endpoint handles GET as well as POST, that the verify token in your code exactly matches the one in the dashboard, and that you respond with the raw hub.challenge value as the body, not wrapped in JSON. In PHP, the parameters arrive as hub_mode, hub_challenge, and hub_verify_token, because PHP converts dots to underscores.
Signature verification fails, especially on non-English messages
Meta signs an escaped-unicode form of the payload. If any middleware parses the JSON and re-serializes it before you verify, characters like é or emoji come out as different bytes, and the signature won’t match. Messages in plain ASCII often still pass, which makes the bug intermittent and hard to spot. Verify against the raw request body, before any JSON parsing. Also check you’re using the app secret, not an access token or the verify token.
“Webhooks Disabled” alert
For Messenger and Instagram, Meta unsubscribed your app after an hour of failed deliveries. Fix the cause, then resubscribe your app to the affected Page or Instagram account. Events from the outage aren’t sent again, so fetch what you missed through the Graph API.
Events never arrive
If verification passed but nothing shows up, the usual cause is that the business asset isn’t connected to your app. A WhatsApp Business Account, Page, or Instagram account needs your app subscribed to it, separately from the field subscriptions in the dashboard. Also confirm you subscribed to the specific field, such as messages, for the right object.
Responding with 201 or 202
Some frameworks default to 201 or 202 for a POST. Meta expects 200, and WhatsApp treats anything else as a failed delivery, retrying it for days. Return a plain 200.
Duplicate messages and bursts after an outage
Retries mean the same message or status can arrive more than once. WhatsApp keeps retrying for up to 7 days, so when a failing endpoint recovers, a large backlog can arrive at once. Deduplicate on the message ID, and make sure your processing can absorb a spike.
Slow responses
A handler that calls an LLM, a CRM, or the Graph API before responding will miss WhatsApp’s latency targets, and slow responses turn into retries and duplicates. Verify the signature, return 200, and process from a queue.
Why use HookDeploy with Meta
The verification handshake is handled for you
HookDeploy’s Meta platform verification preset checks hub.verify_token and echoes hub.challenge at the edge. Meta verifies your callback URL before your handler is deployed, and verification requests are never stored or counted toward your usage. The preset is available on Starter and above.
Keep your app subscribed
Meta unsubscribes Messenger and Instagram apps after an hour of failed deliveries. HookDeploy captures each notification at Cloudflare’s edge and responds with a 200 immediately, before forwarding to your server, so a slow handler, a deploy, or an outage on your side doesn’t count against you. From there:
- Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
- Incidents. Forward failures are grouped into incidents, and you can bulk-replay them at a controlled rate once your server recovers, instead of absorbing Meta’s whole backlog at once.
- History. Meta has no event log or replay API. HookDeploy keeps every captured notification for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.
Signatures survive the trip
Meta’s escaped-unicode signing is unforgiving: any proxy that re-serializes the body breaks it. On first delivery, HookDeploy forwards Meta’s original bytes and X-Hub-Signature-256 header unchanged. That header is on HookDeploy’s protected list: it’s never redacted from stored requests, and custom header strip rules can’t remove it. Because Meta’s signature has no timestamp, retries and replays verify too, no matter how late they arrive.
Two things do break it:
- Transformations. A transformation changes the body, so the signature won’t match at that destination. Use transformations for destinations that don’t verify Meta’s signature, such as analytics or a CRM, and protect those with an injected auth header.
- Privacy filters. Retries and replays send the stored copy of the request. If a privacy filter or body key sanitization changed what was stored, the signature won’t match. Messaging payloads contain personal data, so if you use privacy filters on a Meta endpoint, expect retries and replays to fail verification.
One webhook, many destinations
Send each notification to your bot, a support inbox, and an analytics pipeline in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.
Run your bot where Meta can’t reach it
Meta needs a public HTTPS callback URL. With HookDeploy, that URL belongs to HookDeploy, and the HookDeploy Agent connects outward from your network over mTLS to deliver notifications to a local port. Customer conversations can land on private infrastructure with no public IP or open port.
Develop against real conversations
A tap sends a temporary copy of live notifications from your test number, Page, or Instagram account to 127.0.0.1 on your machine. You can also replay a captured message to your local handler, instead of sending yourself a new WhatsApp message every time you change a line of code.
Know the limits
- Keep the response a 200. Meta expects exactly
200. HookDeploy’s default capture response is a200, so don’t set a custom response with a different status on a Meta endpoint. - Volume. Meta advises sizing WhatsApp webhook capacity for 3 times your outgoing message volume, because every sent message produces status updates. On Free, requests beyond the monthly allowance or the daily limit get a
429, which Meta counts as a failure. Paid plans keep accepting traffic past the included volume.
Retries, replays, and duplicates
Because Meta’s signature doesn’t expire, retries and replays from HookDeploy verify exactly like the original delivery. What you need to handle is duplicates.
Meta’s own retries, HookDeploy’s retries, and your replays can all deliver the same event more than once. Deduplicate on the IDs inside the payload:
- WhatsApp messages: the message
idinmessages[]. - WhatsApp statuses: the message
idplus thestatusvalue, since one message produces several status updates. - Messenger and Instagram messages: the
midinsidemessage.
To reprocess an event on purpose, for example after fixing a bug, clear its ID from your processed list before replaying it.
Set up Meta webhooks with HookDeploy
- In HookDeploy, create an endpoint (for example,
WhatsApp production) and copy its URL. - On the endpoint, open the Security tab, then Verification. Choose Meta as the platform preset and enter a Verify token.
- In your app’s dashboard on developers.facebook.com, open the webhooks configuration for your product (WhatsApp, Messenger, or Instagram).
- Enter your HookDeploy URL as the Callback URL and the same verify token, then click Verify and save. HookDeploy answers the challenge.
- Subscribe to the fields you need, such as
messages, and connect your WhatsApp Business Account, Page, or Instagram account to your app. - In HookDeploy, add a forward destination pointing to your handler, or to an agent for private delivery, and set its retries.
- Send a message to your test number, Page, or Instagram account, and confirm the notification appears in HookDeploy and reaches your handler.
Example handler (Node.js and Express)
HookDeploy answers the verification GET, so your handler only needs the POST.
import crypto from 'node:crypto';
import express from 'express';
const app = express();
// Raw body parser on this route, registered before any global JSON middleware.
// Meta signs an escaped-unicode payload, so never verify a re-serialized body.
app.post('/webhooks/meta', express.raw({ type: 'application/json' }), async (req, res) => {
const signature = req.get('x-hub-signature-256') ?? '';
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.META_APP_SECRET)
.update(req.body) // raw bytes, untouched
.digest('hex');
const valid =
signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
if (!valid) return res.status(401).send('Invalid signature');
res.sendStatus(200); // Meta expects exactly 200
const body = JSON.parse(req.body.toString('utf8'));
for (const entry of body.entry ?? []) {
// WhatsApp, Instagram comments, and Page fields
for (const change of entry.changes ?? []) {
await enqueue({ object: body.object, field: change.field, value: change.value });
}
// Messenger and Instagram messaging
for (const event of entry.messaging ?? []) {
await enqueue({ object: body.object, event });
}
}
// Deduplicate on message IDs in your worker.
});
FAQ
Does HookDeploy handle Meta's hub.challenge verification?
Yes. Turn on the Meta platform verification preset on your endpoint and set your verify token, available on Starter and above. HookDeploy checks hub.verify_token and echoes hub.challenge itself, so Meta verifies your callback URL before your handler exists. Verification requests aren't stored and don't count toward your usage.
Does HookDeploy break X-Hub-Signature-256 verification?
No. HookDeploy forwards Meta's original bytes and X-Hub-Signature-256 header unchanged, which matters because Meta signs an escaped-unicode form of the payload that re-serialization would break. The signature has no timestamp, so retries and replays verify too. Verification fails only when a transformation changes the body, or a privacy filter changed the stored copy used for retries and replays.
Will HookDeploy stop Meta from disabling my webhooks?
Yes, as long as HookDeploy captures the delivery. For Messenger and Instagram, Meta unsubscribes your app after an hour of failed deliveries, and HookDeploy responds to Meta right away even when your server is down. Requests HookDeploy rejects before capture, such as those over a Free plan's limits, still count as failures.
Does this work for WhatsApp, Instagram, and Messenger?
Yes. All three use Meta's Webhooks product, with the same verification handshake and the same X-Hub-Signature-256 signature. They differ in the object and fields you subscribe to and in the payload shape, so your handler branches on the object field.
Why does my signature check fail only on some messages?
Usually because those messages contain non-ASCII characters, like accented letters or emoji. Meta signs an escaped-unicode version of the payload, so any code that parses and re-serializes the JSON before verifying produces different bytes. Verify against the raw request body.
Can I develop a WhatsApp or Messenger bot locally?
Yes. Meta needs a public HTTPS callback URL, so point it at HookDeploy, then start a tap from the Desktop Agent or CLI to copy live events to a local port, or replay a captured event to your local handler.