WhatsApp events notify your application about delivery, engagement, and subscription activity.
Supported Events
| Event | Description |
|---|
whatsapp.sent | Message sent |
whatsapp.failed | Delivery failed |
whatsapp.read | Recipient read the message |
whatsapp.engaged | User interacted with the message |
whatsapp.subscribed | User subscribed |
whatsapp.unsubscribed | User unsubscribed |
whatsapp.message_received | Incoming WhatsApp message received |
The system uses standard spelling whatsapp.message_received for incoming WhatsApp message events.
Every WhatsApp webhook request includes the following headers:
| Header | Description |
|---|
x-cocoon-event-type | Event type (e.g., whatsapp.read) |
x-cocoon-event-datetime | Event time |
x-cocoon-message-id | WhatsApp message ID |
x-cocoon-sender-phonenumber | Sender phone number |
x-cocoon-contact-uuid | Contact UUID |
x-cocoon-contact-whatsapp | Contact WhatsApp number |
Example Payload
{
event_type: str
timestamp: str
status: str
sender: str
receiver: str
content: Optional[str] = None
failure_reason: Optional[str] = None
}
Common Use Cases
- Customer Support Automation: Trigger support tickets or responses when an incoming message is received.
- CRM Synchronization: Track WhatsApp interactions on customer timeline profiles.
- Chatbot Workflows: Feed incoming messages directly into custom chatbot engines.
- Sales Engagement Tracking: Track when users read or engage with template messages.
- Customer Journey Analytics: Monitor read/delivery rates across WhatsApp campaigns.
