WhatsApp Business Platform

The WhatsApp Cloud API Webhook: Where Live Integrations Quietly Break

Your number is registered, your templates are approved, outbound messages send fine. Then a customer replies and nothing reaches your server. Ninety percent of the time the webhook is the culprit — and it fails silently, with no error in your dashboard.

A webhook is how WhatsApp pushes events to your application: inbound messages from customers and delivery/read status updates on the messages you send. Without a correctly configured, verified, and subscribed webhook, your integration is one-way — you can talk, but you can never listen. This is the single most common reason a WhatsApp Cloud API build stalls after setup.

Why the webhook is harder than it looks

Configuring the callback URL in the App Dashboard is a two-minute job. Getting messages to actually arrive is not, because three independent systems all have to line up — and if any one is wrong, Meta simply stops sending, without telling you why.

1. The verification handshake

The moment you save a callback URL, Meta sends your endpoint a GET request with hub.mode, hub.verify_token and hub.challenge. Your server must confirm the token matches and echo back the challenge value with a 200. Get this wrong and the webhook never even activates.

2. Two-level subscription

Subscribing your app to the messages field in the App Dashboard is only half of it. The specific WhatsApp Business Account (WABA) also has to have your app subscribed to it. Miss the second step and verification passes but no messages ever come through.

3. Transport rules

The callback URL must be public HTTPS with a valid, trusted TLS certificate — self-signed certificates are rejected. One endpoint per Meta app. Payloads can be up to 3 MB and must be answered with a fast 200.

4. Signature and retries

Every payload is signed with an X-Hub-Signature-256 header (an HMAC-SHA256 using your app secret) that you should validate. If your endpoint fails or returns a non-200, Meta retries with decreasing frequency for up to 7 days — and duplicate deliveries are expected, so you must de-duplicate.

The verification handshake, in plain terms

When you add or change the callback URL in App Dashboard → WhatsApp → Configuration, Meta immediately calls your endpoint to prove you own it. The request carries three query parameters:

  • hub.mode = subscribeTells your endpoint this is a verification request, not a live event.
  • hub.verify_tokenThe exact string you typed into the Verify Token field. Your code must compare it and reject anything that does not match — this is what stops a stranger pointing Meta at your URL.
  • hub.challengeA value your endpoint has to return, as-is, in the response body with an HTTP 200. Only then does Meta mark the webhook verified.
A mismatched verify token, a URL that is not reachable, or a certificate the browser trusts but Meta does not — any of these makes verification fail, and the Dashboard gives you very little to go on. This is exactly the kind of dead-end where a wrong guess costs a day.

The subscription most developers get half-right

There are two separate switches, and both must be on:

App-level field subscription

In the Configuration panel you subscribe to individual webhook fields. For a messaging build you need the messages field, which delivers both inbound customer messages and the status of messages you send.

WABA-level app subscription

Your app also has to be subscribed to the specific WhatsApp Business Account, via the account's subscribed-apps endpoint. This is the step that is invisible in the UI for many onboarding flows and the one that most often explains ‘verified but silent’ webhooks.

Why your inbound messages never arrive

When outbound works but replies vanish, it is almost always one of these — every item below is behaviour documented by Meta, not guesswork:

  • The app is not subscribed to the WABA. Field subscription is set, but the account-level subscription was never made.
  • The messages field is not subscribed. You subscribed to other fields but not the one that carries messages.
  • The callback URL is not reachable or the TLS certificate is invalid. Self-signed or misconfigured certs are silently refused.
  • The verify token never matched, so the webhook was never activated in the first place.
  • The endpoint is too slow or errors out, so Meta backs off and eventually stops during the retry window.
  • Duplicates are being dropped by your own code, because retries and multi-app delivery produce repeat notifications you were not expecting.
A registered, active phone number is a prerequisite before any of this matters. If the number is not properly registered on the platform, there are no events to deliver in the first place.

Serving other businesses adds an approval gate

If the webhook is for your own WhatsApp Business Account, you can grant the required permissions — whatsapp_business_messaging for message and call webhooks, whatsapp_business_management for the rest — directly with your own system-user token. But if you are a SaaS or partner receiving events for clients’ numbers, those permissions need Advanced Access via App Review before any customer can grant them during onboarding. That is a separate review process on top of getting the webhook itself to fire.

What a correctly wired webhook gives you

2-wayInbound replies and outbound status in real time
≤7dRetry window that protects against short outages when you answer with 200
1Endpoint per app — verified, signed, and de-duplicated

Where this fits

The webhook sits at the end of a chain that includes number registration, display-name approval, message templates and quality rating — each with its own way of stalling. If you are still setting the account up, start with the WhatsApp Cloud API setup guide and the approval walkthrough. If you are connecting many client numbers as a platform, the Embedded Signup and Tech Provider onboarding path is where the webhook and the Advanced Access review come together.

Stuck on a webhook that verifies but stays silent?

This is one of those problems where the configuration looks complete and nothing is technically ‘broken’ — the messages simply do not come. Getting the handshake, the two-level subscription, the TLS setup and the app permissions to all agree is exactly the kind of setup where hands-on help saves days of dead-end debugging.

Guidance only, based on Meta’s official WhatsApp Business Platform documentation as of 2026. Platform requirements change; no specific outcome or timeline can be guaranteed. Not affiliated with or endorsed by Meta.