Overview
The webhook system sends HTTP POST requests to configured URLs whenever WhatsApp events occur. Each webhook request includes event data in JSON format and security headers for verification.Configuration
Environment Variables
Command Line Flags
Event Filtering
You can configure which events are forwarded to your webhook using theWHATSAPP_WEBHOOK_EVENTS environment variable or --webhook-events CLI flag.
Available Events
| Event | Description |
|---|---|
message | Text, media, contact, location, and other message types |
message.reaction | Emoji reactions to messages |
message.revoked | Deleted/revoked messages |
message.edited | Edited messages |
message.ack | Delivery and read receipts |
message.deleted | Messages deleted for the user |
group.participants | Group member join/leave/promote/demote events |
group.joined | You were added to a group |
newsletter.joined | You subscribed to a newsletter/channel |
newsletter.left | You unsubscribed from a newsletter |
newsletter.message | New message(s) posted in a newsletter |
newsletter.mute | Newsletter mute setting changed |
call.offer | Incoming call received |
Configuration Examples
If
WHATSAPP_WEBHOOK_EVENTS is empty or not set, all events are forwarded (default behavior).Security
HMAC Signature Verification
All webhook requests include an HMAC SHA256 signature for security verification:- Header:
X-Hub-Signature-256 - Format:
sha256={signature} - Algorithm: HMAC SHA256
- Default Secret:
secret(configurable via--webhook-secretorWHATSAPP_WEBHOOK_SECRET)
Verification Examples
TLS Configuration
If you encounter TLS certificate verification errors (e.g., with Cloudflare tunnels or self-signed certificates):Payload Structure
All webhook payloads follow a consistent top-level structure:Top-Level Fields
| Field | Type | Description |
|---|---|---|
event | string | Event type (see Available Events table above) |
device_id | string | JID of the device that received this event (e.g., [email protected]) |
payload | object | Event-specific payload data |
Event Examples
Text Message
Image Message
Message Reaction
Delivery Receipt
Group Member Join
Newsletter Joined
Incoming Call
You can auto-reject incoming calls using
WHATSAPP_AUTO_REJECT_CALL=true or --auto-reject-call=true.Implementation Example
Error Handling
The webhook system includes retry logic with exponential backoff:- Timeout: 10 seconds per request
- Max Attempts: 5 retries
- Backoff: Exponential (1s, 2s, 4s, 8s, 16s)
Best Practices
Always verify signatures
Ensure webhook authenticity by validating HMAC signatures
Handle duplicates
The same event might be sent multiple times due to retries
Process quickly
Respond within 10 seconds to avoid timeouts
Use HTTPS
Ensure secure transmission of webhook data
Troubleshooting
Webhook not receiving events
- Check webhook URL is accessible from the internet
- Verify webhook configuration in environment variables
- Check firewall and network settings
Signature verification fails
- Ensure webhook secret matches configuration
- Use raw request body for signature calculation
- Check HMAC implementation matches examples above
Timeouts
- Optimize webhook processing speed
- Implement asynchronous processing
- Return response quickly, process in background
