Webhooks & Events

Rex emits events when things change — contacts created, deals updated, stages moved. Webhooks let you receive these events in real-time at a URL you control.

Events

Every mutation in Rex produces an event. Events are stored and can be polled via the API or pushed to webhook subscribers.

Event types

Polling events

If you prefer pull over push, poll the events endpoint:

curl "$REX_URL/events?after=evt_01HQ...&limit=50" \
  -H "X-Api-Key: $REX_API_KEY"

Response:

{
  "data": [
    {
      "id": "evt_01HQ...",
      "type": "contact.created",
      "timestamp": "2026-03-16T12:00:00Z",
      "data": {
        "id": "cont_01HQ...",
        "email": "ada@example.com"
      }
    }
  ],
  "meta": {
    "cursor": "evt_01HQ...",
    "has_more": false
  }
}

Webhooks

Create a subscription

curl -X POST "$REX_URL/webhooks" \
  -H "X-Api-Key: $REX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/rex",
    "events": ["contact.created", "deal.updated"],
    "secret": "whsec_your_signing_secret"
  }'

Subscribe to specific event types or use ["*"] for all events.

Webhook payload

{
  "event": "contact.created",
  "timestamp": "2026-03-16T12:00:01Z",
  "data": {
    "id": "cont_01HQ...",
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "stage": "lead"
  }
}

Signature verification

Every webhook includes an X-Rex-Signature header:

X-Rex-Signature: t=1710590400,v1=5257a869e7eceb...

The signature is an HMAC-SHA256 of {timestamp}.{payload} using your subscription secret. Always verify signatures to ensure the webhook is genuinely from Rex and hasn't been tampered with.

See Lead Capture Webhook for verification code examples in Node.js and Python.

Retry policy

After 5 failed attempts, the delivery is marked as failed. Failed deliveries are visible in the webhook subscription detail and can be replayed manually.

A delivery is considered failed if your server returns a non-2xx status code or doesn't respond within 10 seconds.

Testing webhooks

Send a test payload to verify your endpoint is working:

curl -X POST "$REX_URL/webhooks/wh_01HQ.../test" \
  -H "X-Api-Key: $REX_API_KEY"

This sends a webhook.test event to your endpoint with a verifiable signature.

Managing subscriptions

Request tracing

Every API response includes an X-Request-Id header. Webhook deliveries include the request ID of the originating mutation. Use this to trace a chain: "API call → event → webhook delivery."