Webhooks allow Cocoonmail to send real-time HTTP notifications whenever specific events occur in your account. Instead of polling the API, your application receives event data immediately after an event is triggered.

​
Typical Use Cases

  • CRM synchronization: Keep customer profiles updated across platforms.
  • Marketing automation: Trigger custom emails, messages, or campaigns.
  • Customer engagement tracking: Monitor opens, clicks, and reads.
  • Analytics: Push data to internal analytics dashboards.
  • Internal workflow automation: Automate business logic when contacts or events change.

​
Creating a Webhook

To create a webhook, follow these steps in your dashboard:
  1. Navigate to Settings → Webhooks.
  2. Click Add Webhook.
  3. Fill in the required configuration options.

​
Webhook Configuration

​
Webhook URL

The public HTTPS endpoint that will receive webhook requests.
  • Example: https://example.com/api/webhooks/cocoonmail
We highly recommend using HTTPS endpoints to ensure webhook payloads are encrypted in transit. Your endpoint must respond within the timeout window and return an HTTP 2xx status code for successful delivery.

​
Authorization (Optional)

An optional authorization header sent with every webhook request to verify that the request is coming from Cocoonmail.
  • Examples:
    • Bearer YOUR_SECRET_TOKEN
    • Basic xxxxxxxxx

​
Select Events

Choose one or more events to subscribe to. You can subscribe to the following event types:

Contact Events

  • contact.created
  • contact.updated
  • contact.deleted

Email Events

  • email.sent
  • email.opened
  • email.clicked
  • email.bounced
  • email.subscribed
  • email.unsubscribed

WhatsApp Events

  • whatsapp.sent
  • whatsapp.failed
  • whatsapp.read
  • whatsapp.engaged
  • whatsapp.subscribed
  • whatsapp.unsubscribed
  • whatsapp.message_received
Only the selected events will be delivered to your webhook URL.

​
Headers and Payloads

​
Reserved Headers

Every webhook automatically includes several Cocoonmail headers that cannot be removed. Depending on the event type, additional headers are automatically included. In the Webhook Builder interface, these are categorized under:
  • Contact Event Headers
  • Email Event Headers
  • WhatsApp Event Headers
You can copy individual headers or all headers directly from the interface.

​
Custom Headers

You may include your own HTTP headers to be sent alongside Cocoonmail’s reserved headers.
  • Examples:
    • x-app-version: 2.0
    • x-tenant: production
    • x-workspace: workspace_123

​
Custom Payload

By default, Cocoonmail sends a standard JSON payload. You can customize the payload by adding additional fields in the Payload Builder. This allows you to:
  • Simplify integrations
  • Include only required fields
  • Create payloads compatible with third-party systems

​
Delivery

Webhooks are delivered using an HTTP POST request.

​
Example Request

POST https://example.com/api/webhooks/cocoonmail
Content-Type: application/json
Payload
{
    // Event details
}

​
Best Practices

To ensure reliable webhook delivery and processing:
  1. Return HTTP 200 immediately: Acknowledge receipt of the webhook before performing long-running or downstream tasks.
  2. Process webhooks asynchronously: Use a queue or background worker to process the payload.
  3. Validate authorization headers: Ensure requests are authentic before taking action.
  4. Log webhook requests: Store raw payloads and headers to assist with debugging.
  5. Retry logic: Implement retries for downstream systems in case of failures.
  6. Use HTTPS: Secure your webhook endpoint with SSL/TLS.