WhatsApp Webhook Not Receiving Messages: A Checklist

If your WhatsApp webhook isn’t receiving messages, the cause is almost always one of five things: the app isn’t subscribed to the messages field, the app isn’t subscribed to your WhatsApp account (/<WABA_ID>/subscribed_apps), the app is in Development mode, an override sends events to another URL, or your endpoint isn’t answering with 200.

This checklist takes you through each one in the order that finds the problem fastest, using only checks that Meta documents. How verification, signatures and payloads work is in our WhatsApp Cloud API webhooks guide; this post is for when it’s set up and still silent.

Step 1: find out which side is broken

Before changing anything, split the problem in two. Either Meta isn’t sending events to you, or it is and your code isn’t handling them. Meta’s own troubleshooting steps come down to three checks:

1. Confirm your endpoint accepts requests. Call it from outside your network. It must be on HTTPS with a valid certificate; self-signed certificates aren’t supported.
2. Send a test payload from the App Dashboard, in the WhatsApp Configuration panel (for apps created with the “Connect with customers through WhatsApp” use case: Use cases › Customize › Configuration). Pick the messages field.
3. Compare with Meta’s test webhook endpoint. Meta’s guide shows how to deploy a small test endpoint that prints every request it receives. If it shows the payloads and yours doesn’t, the problem is in your endpoint or code.

If the test payload reaches you but real customer messages don’t, Meta’s side is sending; work through the account checks below. If even the test payload doesn’t arrive, start with your URL, certificate and firewall.

The checklist

Work down this list. Each item is a documented requirement for receiving events.

The account subscription: the most missed step

Subscribing to the messages field in the App Dashboard isn’t enough on its own. Meta says you “must individually subscribe to every Messaging account” you want webhooks for. This catches people who add a second account, or who onboard customers as a provider.

• Subscribe: POST https://graph.facebook.com/v26.0/<WABA_ID>/subscribed_apps with Authorization: Bearer <TOKEN>. Success returns {"success": true}.
• Check: GET /<WABA_ID>/subscribed_apps returns the apps, by ID and name, that receive that account’s events. If yours isn’t in the list, it won’t get messages.
• Remove: DELETE /<WABA_ID>/subscribed_apps unsubscribes your app, so check that a clean-up script hasn’t done this.

Every subscribed account sends its events to the callback URL set in your app, unless an override says otherwise. Not sure which ID is the WABA ID? See how to find your WhatsApp Business Account ID.

Live mode, permissions and App Review

Meta’s webhooks overview says: make sure your app is in Live mode, because “some webhooks will not be sent if your app is in Dev mode.” Meta’s test endpoint guide adds a useful detail: messages test webhooks work in both modes. So a test payload arriving while real messages don’t is a typical sign of an app still in Development mode.

Permissions decide which fields you can receive. Meta lists whatsapp_business_messaging for the messages (and calls) webhooks and whatsapp_business_management for everything else, such as template status and account updates. If you’re a provider onboarding other businesses, Meta says you need Advanced access to these permissions through App Review before your customers can grant them.

Overrides: events going to another URL

Meta lets you set an alternate callback URL on a WhatsApp account or on a single phone number. When a webhook fires, Meta uses the first one it finds in this order: the phone number’s override, then the account’s override, then the app’s callback URL. An old override left behind by a test, a previous provider or a staging setup will quietly send that number’s messages somewhere else.

Ask Meta directly which URLs apply: GET /<PHONE_NUMBER_ID>?fields=webhook_configuration. The response lists phone_number, whatsapp_business_account and application. A phone_number or whatsapp_business_account entry means an override is in place for that number or account; if neither appears, events go to the app’s URL.

Your endpoint: 200s, signatures and batches

Once Meta is sending, events can still be lost in your own code. Check these:

• Return 200 fast. Any other response makes Meta retry, with decreasing frequency, for up to 7 days. After that the event is dropped, and Meta has no API for fetching old webhook data.
• Don’t break your own signature check. If you parse the JSON before computing X-Hub-Signature-256, the bytes change, every check fails and you reject real events. Hash the raw body; details in our webhooks guide.
• Loop over everything. Meta can batch up to 1,000 updates in one POST, though Meta may not batch them. Code that only reads entry[0].changes[0] misses the rest.
• Handle messages and statuses separately. Both come in the messages field: customer messages under value.messages[], your delivery updates under value.statuses[]. If you only see statuses, check that your handler reads messages too.
• De-duplicate. Retries can deliver the same event twice. Store message IDs and ignore repeats.
• Accept large payloads. Webhooks can be up to 3 MB, so a small request-size limit on your server can reject them.
• Firewall rules. Meta changes its IP addresses from time to time, so an IP allow-list can start blocking it. Meta recommends mutual TLS instead.

Symptoms and likely causes

Still on Meta’s test number? Its own quirks, such as To numbers and short-lived tokens, are covered in why the WhatsApp API test number is not working. If your sends fail too, look the code up in WhatsApp API error codes.

Messages missed while you were down

Because Meta retries for up to 7 days, fixing your endpoint quickly usually brings the missed events in, perhaps out of order. Process them by their timestamp rather than arrival time. Anything older than 7 days is gone, so if customers wrote in during a long outage, check the conversation from your side and reply with a template if their 24-hour window has closed.

Webhooks with Automate AI

With Automate AI you don’t host the WhatsApp webhook at all. When you connect your number, Automate AI subscribes to your account’s webhooks and points them to its own callback URL, and incoming messages appear in the shared inbox. If your own systems need events, the REST API and developer webhooks (events such as message received and message status update) are included on Series 2, 3 and 4 plans; see the WhatsApp Business API page and pricing.