WhatsApp Webhook Events

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
`whatsapp.template_approved`	Template approved
`whatsapp.template_rejected`	Template rejected

The system uses standard spelling whatsapp.message_received for incoming WhatsApp message events.

Reserved Headers

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.

Email Events Overview

Get started

Contacts

Workflow builder

Events

Transactional email

Whatsapp

API

Webhooks

Integrations

Deliverability

SDKs

Account

Supported Events

Reserved Headers

Example Payload

Common Use Cases

​Supported Events

​Reserved Headers

​Example Payload

​Common Use Cases

Supported Events

Reserved Headers

Example Payload

Common Use Cases