Webhooks are the primary mechanism for receiving real-time updates from the WhatsApp Business API. This guide covers everything developers need to know.
What Are Webhooks?
When something happens on WhatsApp (message received, message delivered, status changed), Meta sends an HTTP POST request to your configured webhook URL with details about the event.
Setting Up Webhooks
1. Create an Endpoint
Set up an HTTPS endpoint that can receive POST requests. Your endpoint must:
- Respond with 200 OK within 5 seconds
- Handle verification challenges (GET requests)
- Process events asynchronously
2. Verify Your Webhook
Meta sends a GET request with a verification challenge. Respond with the challenge token to confirm ownership.
3. Handle Events
Common webhook events:
- `messages`: New incoming messages
- `statuses`: Message delivery status updates (sent, delivered, read)
- `contacts`: Contact information updates
- `errors`: Delivery failures
4. Secure Your Webhook
- Validate the X-Hub-Signature header using your app secret
- Use HTTPS only
- Implement IP allowlisting if possible
- Rate limit incoming requests
Best Practices
- Process webhooks asynchronously (queue + worker pattern)
- Implement retry logic for failed processing
- Log all webhook payloads for debugging
- Set up monitoring and alerting for webhook failures
- Handle duplicate events gracefully (idempotency)
Related: WhatsApp API security overview
FAQ
Why am I getting duplicate webhooks?
Meta retries webhook delivery if your server doesn't respond with 200 OK. Always implement idempotency checks using the message ID.
Do webhooks work for groups?
If your API number is in a group, you will receive webhooks for messages sent to that group.
Can I use a local development URL?
Yes, but you'll need a tool like ngrok to provide a secure public HTTPS URL for Meta to hit.
What is the Hub Challenge?
It's a one-time verification step where Meta sends a string that you must echo back to prove you control the endpoint.`,
