Webhooks

Receive real-time event notifications from SuperWaba via HTTP webhooks.

Setup

1. Go to Settings > Integrations > Webhooks
2. Click Add Webhook
3. Enter your endpoint URL (must be HTTPS)
4. Select the events you want to receive
5. Copy the signing secret for verification

Events

Event	Trigger
message.received	New incoming message from a customer
message.sent	Message sent to a customer (by agent or AI)
conversation.created	New conversation started
conversation.closed	Conversation marked as closed
conversation.assigned	Conversation assigned to a team member
contact.created	New contact added
contact.updated	Contact details changed
ai.escalated	AI agent escalated to human

Payload format

All webhook payloads follow this structure:

{
  "event": "message.received",
  "timestamp": "2026-05-16T12:00:00Z",
  "org_id": "uuid",
  "data": {
    // Event-specific data
  }
}

Verifying signatures

Every webhook request includes an X-SuperWaba-Signature header. Verify it using HMAC-SHA256:

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry policy

Failed deliveries (non-2xx response) are retried up to 3 times with exponential backoff:

• 1st retry: 1 minute
• 2nd retry: 5 minutes
• 3rd retry: 30 minutes

After 3 failures, the webhook is marked as failing. Fix the endpoint and re-enable from the dashboard.

Testing

Use the Test button in the webhook settings to send a sample payload to your endpoint.