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 Queue as Delivery queue
    participant You as Your endpoint

    Note over Unexus: Event occurs (e.g. call.status)
    Unexus->>Queue: One delivery per subscription
    Queue->>You: POST (JSON envelope), attempt 1
    You-->>Queue: 5xx / timeout
    Note over Queue: wait 10 s
    Queue->>You: POST (same envelope), attempt 2
    You-->>Queue: 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
X-UCS-Attempt: 1

{ ...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 the delivery. Identical on every retry of the same event, so use it as your idempotency key and in support requests.
X-UCS-Attempt	One-based attempt counter. 1 is the first delivery; anything higher is a retry of a delivery you did not acknowledge.

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, stable across retries. 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). Does not change on retry.
tenant	string | null	The Unexus tenant the event belongs to.
data	object	Event-specific payload. See the event catalog.

The body bytes are identical on every attempt of the same delivery.

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 attempt.
• At-least-once with retries — a delivery that fails for a transient reason is retried on a fixed schedule. The default schedule waits 10 seconds, 1 minute, 5 minutes, 30 minutes, 2 hours, 4 hours and 6 hours between attempts, i.e. eight attempts over roughly 12 h 36 min (installation configurable). After the last attempt the delivery is parked on the Unexus side for inspection and is not retried automatically. Because a retry can succeed after your endpoint already processed an earlier attempt that timed out, you may receive the same delivery more than once.
• What is retried — connection failures, timeouts, and the response codes 408, 425, 429 and every 5xx.
• What is not retried — any other 4xx and redirects. These indicate a problem another attempt will not fix (wrong URL, rejected credential, malformed request). Such deliveries are parked immediately.
• No ordering guarantee — events may arrive out of order, and retries make this more likely: a retried event arrives after newer events that were delivered successfully. Use occurredAt (and your own state) rather than arrival order.
• Independent per subscription — each subscription has its own attempts and its own failure history. A failing subscriber never affects delivery to other subscribers.
• Endpoint outage protection — when an endpoint keeps failing, Unexus stops contacting it for a short cool-down and lets the pending retries wait for their next slot instead of timing out one by one. Deliveries are not lost by this; they follow the retry schedule above.

See best practices for how to build a robust receiver.