Webhooks

Webhooks let your server receive real-time HTTP notifications when events happen in Active Reach. Instead of polling the API, you register a URL and Active Reach pushes events to you.

How it works

You register a webhook URL in Settings → Developer → Webhooks
You subscribe to specific event types (e.g., delivery.delivered, contact.created)
When a subscribed event occurs, Active Reach sends an HTTP POST to your URL with a JSON payload
Your server responds with 2xx to acknowledge receipt

If your server doesn’t respond with 2xx, Active Reach retries with exponential backoff (see Retry policy).

Setting up a webhook

Register your endpoint

Go to Settings → Developer → Webhooks → Add webhook.

URL — your server’s HTTPS endpoint (HTTP not allowed in production)
Description — a label for this webhook (e.g., “Data warehouse sync”)

Select event types

Choose which events to receive. See Event types for the full list. Common starting set:

delivery.delivered — a message was delivered
delivery.bounced — a message bounced
delivery.clicked — a recipient clicked a link
contact.created — a new contact appeared
contact.updated — a contact’s properties changed

Get your signing secret

After creation, Active Reach shows a signing secret — a 64-character hex string used as the HMAC key when signing webhook payloads. Store it securely. Secrets can be rotated from the same page. See Signature verification.

Test the connection

Click Test to fire a sample payload to your URL. Verify your server responds 200 and processes the payload correctly.

Payload format

Every webhook delivery is a JSON POST with this structure:


{
  "id": "evt_a1b2c3d4e5f6",
  "type": "delivery.delivered",
  "timestamp": "2026-04-17T10:30:00.000Z",
  "workspace_id": "ws_abc123",
  "data": {
    "message_id": "msg_xyz789",
    "campaign_id": "camp_welcome_q2",
    "contact_id": "usr_456",
    "channel": "email"
  }
}

Field	Description
`id`	Unique event ID (for deduplication)
`type`	Event type (e.g., `delivery.delivered`)
`timestamp`	ISO 8601 timestamp
`workspace_id`	The workspace that generated the event
`data`	Event-specific payload (varies by type)

What’s next

Event types — full catalog of webhook event types
Signature verification — validate webhook authenticity
Retry policy — backoff and dead-letter behavior
Testing webhooks — tools for local development