Meta Webhooks

Meta Webhook Signature Verification: Where WhatsApp, Messenger and Instagram Integrations Quietly Fail

Every Meta webhook payload arrives with an X-Hub-Signature-256 header, and before that, a one-time verify_token handshake. Both look like a five-minute checkbox on a setup guide. Both are also where a surprising number of otherwise-working integrations quietly break, with no error message pointing at the real cause.

WhatsApp Cloud API messages, Messenger Page events, and Instagram DM and comment notifications all run on the same Meta Graph API webhooks framework, with the same two checkpoints: a verification handshake when the endpoint is first registered, and a signature check on every event notification after that. Get either one wrong and the result is one of two failure modes — the webhook never activates, or it activates but nothing confirms that what is arriving is genuinely from Meta and untampered.

What Meta Sends You, and What It Expects Back

The verify_token handshake

When you save a callback URL in the App Dashboard, Meta sends a one-time GET request carrying hub.mode=subscribe, hub.verify_token and hub.challenge. Your endpoint has to confirm the token matches the value you set, then echo the hub.challenge value back as the response. Get it wrong and the Dashboard just marks the URL unverified — with almost nothing else to go on.

The X-Hub-Signature-256 header

Every Event Notification after that carries an X-Hub-Signature-256 header formatted as sha256=<digest> — an HMAC-SHA256 signature computed over the payload using your app's App Secret. Recomputing that same HMAC on your side and comparing it is how you confirm the payload actually came from Meta and was not altered in transit.

The TLS requirement

Both request types only reach a server presenting a valid TLS certificate from a recognised certificate authority. Self-signed certificates are explicitly rejected by Meta's webhook delivery system, and the failure again shows up as a silent timeout rather than a clear error.

The Overview, Not the Full Build

  • Stand up one HTTPS endpoint with a trusted, publicly issued certificateThis is the single address every product line — WhatsApp, Messenger, Instagram — will call, so it has to hold up under all three at once.
  • Handle the one-time verification GET requestMatch the verify_token exactly, then return the hub.challenge value as the response body.
  • Recompute and compare the signature on every POST eventDerive the HMAC-SHA256 digest from the app secret and the exact payload bytes before you trust or process anything in the request.
  • Subscribe the right object to the right fieldsA verified callback URL does not by itself mean events are flowing — the Page, WABA, or Instagram professional account still has to be subscribed to the specific fields you need. The WhatsApp Cloud API webhook setup guide covers this two-level subscription in detail.
  • Acknowledge fast and expect duplicatesMeta resends on failure, so the endpoint has to respond quickly and handle repeat deliveries without double-processing them.

Why This Is Easy to Get Subtly Wrong

✕Comparing the signature against a re-serialized copy of the JSON instead of the exact raw request body — re-encoding changes the bytes, and the HMAC will never match again even with the correct secret.
✕Validating against a stale App Secret after it was reset or regenerated in the App Dashboard — the signature check keeps failing until every server using the old secret is updated.
✕Running multiple apps or client businesses through the same stack, each with its own App Secret — validating an event against the wrong app's secret produces a mismatch that looks identical to a tampered payload.
✕A verify_token that was hardcoded once and never kept in sync between the App Dashboard and the live server configuration.
✕A TLS certificate that looks fine in a browser but is self-signed or missing an intermediate — Meta's verification rejects it while local testing shows no problem at all.
✕If this same endpoint is part of an active Meta App Review submission, a broken webhook is treated as a hard rejection during testing, not a warning — see the webhook App Review blocker guide for what reviewers actually test.

Getting the Handshake and the Signature Check Right the First Time

None of these failure points produce a clear, single error message. A webhook that looks fully configured in the App Dashboard can still be silently rejecting every event, or worse, accepting payloads without ever confirming they genuinely came from Meta. For a SaaS platform or agency juggling several apps, App Secrets, and client WhatsApp Business Accounts at once, keeping the handshake, the signature check, and the certificate requirements aligned across WhatsApp, Messenger, and Instagram webhooks is exactly the kind of setup work worth having reviewed by someone who does it regularly.

Review preparation and technical implementation support for webhook and permission setups is covered under the WhatsApp App Review support service.

Guidance only, based on Meta's publicly available developer documentation as of 2026 (Graph API Webhooks and Instagram Platform Webhooks docs). Platform requirements can change without notice. Not affiliated with or endorsed by Meta Platforms, Inc.