Webhooks API

Subscribe to real-time event notifications. Rex pushes events to your HTTPS endpoint as they happen, so you don't need to poll.

Endpoints

Method	Path	Description
POST	`/webhooks`	Create a webhook subscription
GET	`/webhooks`	List webhook subscriptions
GET	`/webhooks/:id`	Get a webhook subscription
PATCH	`/webhooks/:id`	Update a webhook subscription
DELETE	`/webhooks/:id`	Delete a webhook subscription
GET	`/webhooks/:id/deliveries`	List delivery attempts
POST	`/webhooks/:id/ping`	Send a test ping
POST	`/webhooks/:id/replay`	Replay events from a point in time

Create a webhook subscription

POST /webhooks

Request body

Field	Type	Required	Description
`name`	string	yes	Human-readable name
`url`	string	yes	HTTPS endpoint URL
`secret`	string	no	Signing secret (auto-generated if omitted)
`event_types`	array of strings	no	Event types to subscribe to (all if omitted)
`metadata`	object	no	Arbitrary key-value data

Example

curl -X POST "$REX_URL/webhooks" \
  -H "X-Api-Key: $REX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM Sync",
    "url": "https://example.com/webhooks/rex",
    "event_types": ["contact.created", "deal.won", "deal.lost"]
  }'

Response

The create response includes the signing secret -- store it securely, as it is not returned again.

{
  "data": {
    "id": "whk_01HQ...",
    "name": "CRM Sync",
    "url": "https://example.com/webhooks/rex",
    "event_types": ["contact.created", "deal.won", "deal.lost"],
    "status": "active",
    "failure_count": 0,
    "created_at": "2026-03-16T12:00:00Z",
    "updated_at": "2026-03-16T12:00:00Z"
  },
  "secret": "whsec_..."
}

List webhook subscriptions

GET /webhooks

Query parameters

Parameter	Type	Description
`cursor`	string	Pagination cursor
`limit`	integer	Results per page (default 50, max 200)
`status`	string	Filter by status: `active`, `paused`, `disabled`

Example

curl "$REX_URL/webhooks" \
  -H "X-Api-Key: $REX_API_KEY"

Response

{
  "data": [
    {
      "id": "whk_01HQ...",
      "name": "CRM Sync",
      "url": "https://example.com/webhooks/rex",
      "event_types": ["contact.created", "deal.won", "deal.lost"],
      "status": "active",
      "last_delivered_at": "2026-03-16T11:55:00Z",
      "failure_count": 0,
      "created_at": "2026-03-16T12:00:00Z",
      "updated_at": "2026-03-16T12:00:00Z"
    }
  ],
  "has_more": false
}

Get a webhook subscription

GET /webhooks/:id

Example

curl "$REX_URL/webhooks/whk_01HQ..." \
  -H "X-Api-Key: $REX_API_KEY"

Response

Same shape as list items above, wrapped in { "data": ... }.

Update a webhook subscription

PATCH /webhooks/:id

Request body

Field	Type	Required	Description
`name`	string	no	Human-readable name
`url`	string	no	HTTPS endpoint URL
`secret`	string	no	New signing secret
`event_types`	array of strings	no	Event types to subscribe to
`status`	string	no	Status: `active`, `paused`, `disabled`
`metadata`	object	no	Arbitrary key-value data

Re-enabling a disabled subscription resets its failure count to 0.

Example

curl -X PATCH "$REX_URL/webhooks/whk_01HQ..." \
  -H "X-Api-Key: $REX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused"
  }'

Response

Returns the full updated subscription.

Delete a webhook subscription

DELETE /webhooks/:id

Example

curl -X DELETE "$REX_URL/webhooks/whk_01HQ..." \
  -H "X-Api-Key: $REX_API_KEY"

Response

204 No Content on success.

List delivery attempts

GET /webhooks/:id/deliveries

Audit log of delivery attempts for a subscription.

Query parameters

Parameter	Type	Description
`cursor`	string	Pagination cursor
`limit`	integer	Results per page (default 50, max 200)
`status`	string	Filter by delivery status: `success`, `failed`, `pending`

Example

curl "$REX_URL/webhooks/whk_01HQ.../deliveries?status=failed" \
  -H "X-Api-Key: $REX_API_KEY"

Response

{
  "data": [
    {
      "id": "whd_01HQ...",
      "subscription_id": "whk_01HQ...",
      "event_id": "evt_01HQ...",
      "attempt": 3,
      "status": "failed",
      "http_status": 500,
      "error": "Internal Server Error",
      "duration_ms": 1200,
      "created_at": "2026-03-16T12:01:00Z"
    }
  ],
  "has_more": false
}

Send a test ping

POST /webhooks/:id/ping

Sends a test payload to the webhook endpoint and returns the result.

Example

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

Response

{
  "data": {
    "http_status": 200,
    "duration_ms": 150
  }
}

If the endpoint returns a non-2xx status, the response will include an error field and a 502 Bad Gateway HTTP status.

Replay events

POST /webhooks/:id/replay

Resets the subscription's event bookmark to a specific event ID. Events after that point will be re-delivered on the next dispatch cycle.

Request body

Field	Type	Required	Description
`event_id`	string	yes	Event ID to replay from

Example

curl -X POST "$REX_URL/webhooks/whk_01HQ.../replay" \
  -H "X-Api-Key: $REX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "evt_01HQ..."
  }'

Response

Returns the updated webhook subscription.

Delivery behavior

Each event batch is retried up to 5 times with exponential backoff (0s, 30s, 2m, 10m, 1h).
After 20 consecutive failures, the subscription is automatically disabled.
Re-enabling via the API resets the failure count.
On any successful delivery, the failure count resets to 0.

Was this page helpful?

Events

Schema