Webhook Configuration for WhatsApp API
Webhooks let your application receive real-time notifications when events happen on your WhatsApp Business account, such as incoming messages, delivery confirmations, and status updates. Instead of constantly polling the API for changes, your server gets an instant HTTP POST request the moment something happens. This guide covers setting up secure, reliable webhook endpoints.
Step-by-Step Instructions
- 1
Create your webhook endpoint
Build an HTTPS endpoint on your server that can receive POST requests. The endpoint must respond with a 200 status code within 20 seconds to acknowledge receipt. Use a framework like Express (Node.js), Flask (Python), or any web server that can handle HTTP requests. During development, tools like ngrok can expose your local server to the internet for testing.
- 2
Implement the verification handshake
WhatsApp sends a GET request to verify your webhook URL before activating it. Your endpoint must read the hub.mode, hub.verify_token, and hub.challenge query parameters. If hub.mode is 'subscribe' and hub.verify_token matches the token you configured, respond with the hub.challenge value. This one-time handshake proves you control the endpoint.
- 3
Register the webhook URL in your dashboard
Go to your SuperWaba dashboard or Meta App Dashboard and enter your webhook URL. Select which events you want to subscribe to: messages (incoming texts, media, locations), message status updates (sent, delivered, read), and account events. Enter your verification token and click Verify. Meta will send the handshake request to confirm your endpoint is working.
- 4
Parse and process incoming payloads
Incoming webhook payloads are JSON objects with a specific structure. Each payload contains an array of entries, each with an array of changes. Parse the message type (text, image, document, location, interactive reply) and extract the relevant data. Store messages in your database and trigger appropriate business logic like auto-replies, CRM updates, or notification dispatches.
- 5
Add signature verification for security
Every webhook request from Meta includes an X-Hub-Signature-256 header containing an HMAC-SHA256 signature of the payload. Verify this signature using your app secret before processing any request. This prevents malicious actors from sending fake webhook events to your endpoint. Reject any request where the signature does not match.
- 6
Implement retry handling and error resilience
If your endpoint returns an error or times out, Meta will retry the delivery with exponential backoff. Design your handler to be idempotent so processing the same event twice does not cause problems (use message IDs for deduplication). Set up monitoring and alerting so you are notified immediately if your webhook endpoint goes down or starts returning errors.
Pro Tips
- Always respond with a 200 status code immediately, then process the webhook payload asynchronously. Long processing times will cause Meta to mark your endpoint as unhealthy.
- Log every incoming webhook payload during development. These raw logs are invaluable for debugging message parsing issues and understanding the payload structure.
- Use a message queue (like Redis, RabbitMQ, or SQS) between your webhook receiver and your processing logic. This decouples reception from processing and prevents data loss during traffic spikes.
- Set up a health check endpoint alongside your webhook and monitor it with an uptime service. Webhook failures can silently break your entire messaging pipeline if undetected.
Ready to get started?
Start your free 14-day trial and put this guide into action.