Webhook Subscriptions API

Manage the webhook subscriptions that determine which events Unexus delivers to your endpoint. See the Webhooks overview for how delivery works.

Base path: /api/v1/webhooks/subscriptions All endpoints require authentication.

The subscription object

{
  "id": "1f0c5a2e-8b4d-4a5e-9c3f-7d2e6b1a9f04",
  "url": "https://example.com/unexus/events",
  "eventTypes": ["call.status", "agent.status"],
  "description": "CRM integration",
  "enabled": true,
  "createdAt": "2026-07-21T09:15:23.412+00:00"
}

Field	Type	Description
`id`	string (GUID)	Unique subscription identifier. Use this in URLs.
`url`	string	Your HTTPS endpoint that receives event deliveries.
`eventTypes`	string[]	Event types this subscription receives. See the event catalog.
`description`	string \| null	Free-form label for your own administration.
`enabled`	boolean	Only enabled subscriptions receive deliveries.
`createdAt`	string (ISO 8601)	When the subscription was created (UTC).

Create a subscription

POST /api/v1/webhooks/subscriptions

Request body:

{
  "url": "https://example.com/unexus/events",
  "eventTypes": ["call.status", "agent.status"],
  "description": "CRM integration"
}

Field	Required	Notes
`url`	yes	Absolute `http(s)` URL. Use HTTPS in production.
`eventTypes`	yes	At least one known event type. Unknown types are rejected.
`description`	no	Free text.

Responses:

201 Created — returns the created subscription object; the Location header points to the new resource.
400 Bad Request — invalid URL or unknown/missing event types. The body describes the problem and lists the known event types.

Example:

curl -X POST "https://{host}/api/v1/webhooks/subscriptions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/unexus/events","eventTypes":["call.status"]}'

List subscriptions

GET /api/v1/webhooks/subscriptions

Returns 200 OK with an array of subscription objects.

Get a subscription

GET /api/v1/webhooks/subscriptions/{id}

Returns 200 OK with the subscription object, or 404 Not Found.

Delete a subscription

DELETE /api/v1/webhooks/subscriptions/{id}

Returns 204 No Content on success, or 404 Not Found if the id does not exist. New deliveries to the endpoint stop immediately. Deliveries that were already failing and waiting for a retry keep their schedule and may still arrive for up to about 12 h 36 min (the default retry window); answer them with any 4xx and they are parked instead of retried.