Webhook Events

SuperWaba sends real-time HTTP POST requests to your endpoint when events occur. This page covers the shared basics — the common envelope, headers, and metering. Individual events are documented on dedicated pages:

• Message Events — message.received, message.sent, message.delivered, message.read, message.failed
• Contact Events — contact.created, contact.updated
• Conversation Events — conversation.opened, conversation.closed
• Server Examples — cURL test, Express.js, and Python Flask receiver examples

See the Webhooks integration guide for setup instructions.

---

Common envelope

Every webhook delivery follows this structure:

{
  "event": "event.name",
  "timestamp": "2026-05-16T12:00:00.000Z",
  "webhook_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "data": {
    // Event-specific payload - see each event below
  }
}

Headers

Every request includes these headers:

Header	Example	Description
Content-Type	application/json	Always JSON
X-Webhook-Event	message.received	The event type
X-Webhook-Delivery-Id	a1b2c3d4-...	Unique delivery ID (for deduplication)
X-Webhook-Secret	whsec_abc123...	Your webhook secret (if configured)

Expected response

Your endpoint should return a 2xx status code within 10 seconds. Any non-2xx response is treated as a failure.

HTTP/1.1 200 OK

---

Monthly Event Metering

Webhook event deliveries and Developer API send-message calls share a single monthly event counter per organization. When the cap is reached, both webhook deliveries and API calls are blocked until the next billing cycle.

Plan	Monthly Events
Insta / Starter	5,000
Growth	10,000
Pro	50,000
Enterprise	Unlimited

When the limit is reached, webhook events are silently dropped (logged as a warning), and Developer API calls return a 429 response.

You can monitor your current usage in Settings → Developer → API Logs.

---

Multi-Channel Events

Webhook events are fired for all connected channels - WhatsApp, Instagram, and Messenger. The data.channel field identifies the source:

{
  "event": "message.received",
  "data": {
    "channel": "instagram",
    "message_id": "mid.XXXX",
    "from": "17841400000000000",
    "contact_name": "Priya Sharma",
    "type": "text",
    "content": { "text": "Hi there!" }
  }
}

Channel	channel value	Identifier field
WhatsApp	"whatsapp"	Phone number (+91...)
Instagram	"instagram"	Instagram-scoped ID
Messenger	"messenger"	Page-scoped ID (PSID)

---

Event lifecycle diagram

A typical WhatsApp conversation triggers events in this order:

Customer sends first message
  → contact.created
  → conversation.opened
  → message.received

AI agent replies
  → message.sent (is_ai: true)
  → message.delivered
  → message.read

Customer replies again
  → message.received

Human agent takes over and replies
  → message.sent (sender_id: "user-uuid")
  → message.delivered

Conversation closes after idle timeout
  → conversation.closed (closed_by: "auto")