Webhooks overview

Webhooks let Unexus notify your application the moment something happens in the contact center — no polling. You register an HTTPS endpoint once, and Unexus delivers each subscribed event to it as an HTTP POST.

sequenceDiagram
    participant Unexus as Unexus platform
    participant Delivery as Webhook delivery
    participant You as Your endpoint

    Note over Unexus: Event occurs (e.g. call.status)
    Unexus->>Delivery: Publish event
    Delivery->>You: POST (JSON envelope)
    You-->>Delivery: 2xx acknowledges

Subscribing

Register your endpoint via the Webhook Subscriptions API. A subscription couples one URL to one or more event types. Only enabled subscriptions receive deliveries.

The delivery request

Every delivery is an HTTP POST to your subscription URL:

POST /your/endpoint HTTP/1.1
Content-Type: application/json; charset=utf-8
X-UCS-Event: call.status
X-UCS-Delivery: 8f7c1a4e-2d3b-4c5a-9e8f-6a7b8c9d0e1f

{ ...envelope... }

Header	Description
X-UCS-Event	The event type of this delivery (e.g. call.status). Lets you route without parsing the body.
X-UCS-Delivery	Unique id of this delivery attempt. Use it for idempotency and support requests.

The envelope

Every event body has the same outer shape; only data differs per event type:

{
  "deliveryId": "8f7c1a4e-2d3b-4c5a-9e8f-6a7b8c9d0e1f",
  "eventType": "call.status",
  "occurredAt": "2026-07-21T09:15:23.412+00:00",
  "tenant": "customer.unexus.nl",
  "data": { }
}

Field	Type	Description
deliveryId	string (GUID)	Unique per delivery. Matches the X-UCS-Delivery header.
eventType	string	Event type identifier. Matches the X-UCS-Event header.
occurredAt	string (ISO 8601)	When the event occurred (UTC).
tenant	string | null	The Unexus tenant the event belongs to.
data	object	Event-specific payload. See the event catalog.

Responding to a delivery

• Return any 2xx status code to acknowledge the delivery.
• Respond fast (well under 10 seconds — see timeout below). Queue the event internally and process it asynchronously; do not do heavy work in the request handler.
• The response body is ignored.

Delivery semantics

Understand these guarantees when designing your consumer:

• Timeout — deliveries time out after 10 seconds (installation configurable). A timeout counts as a failed delivery.
• No retries (at-most-once) — if your endpoint is unreachable, times out, or returns a non-2xx status, that delivery is logged on the Unexus side and not retried. Treat webhooks as a real-time signal; if you need guaranteed completeness, periodically reconcile via the REST API.
• No ordering guarantee — events may arrive out of order, especially under load. Use occurredAt (and your own state) rather than arrival order.
• Independent per subscription — a failure of one subscriber never affects delivery to other subscribers.

See best practices for how to build a robust receiver.