Concepts
Webhooks
Real-time event delivery to your application
Webhooks notify your application when events occur on a WhatsApp connection — incoming messages, delivery receipts, status changes, and more.
How it works
WhatsApp → WAHA Pod → WAHooks API → BullMQ Queue → Your Webhook URL- A WhatsApp event occurs (message received, status change, etc.)
- WAHA forwards it to the WAHooks API
- The API matches the event to your webhook configs
- The event is enqueued for reliable delivery via BullMQ
- The delivery processor sends an HTTP POST to your URL
Event filtering
Each webhook config has an events array that controls which events are delivered:
["*"]— receive all events (default)["message"]— only incoming messages["message", "message.any"]— incoming + outgoing messages["session.status"]— only session status changes
Delivery guarantees
| Property | Value |
|---|---|
| Retry attempts | 5 |
| Backoff | Exponential: 5s, 10s, 20s, 40s, 80s |
| Timeout | 15 seconds per attempt |
| Dead letter queue | Last 1000 failed deliveries retained |
Your endpoint must return a 2xx status code within 15 seconds, otherwise the delivery is retried.
Multiple webhooks
You can create multiple webhook configs per connection. Each receives events independently — useful for sending different event types to different services.
Delivery logs
Every webhook delivery is logged with status, attempt count, and the full payload. Use the logs endpoint or CLI to inspect deliveries:
wahooks webhooks logs WEBHOOK_ID