Public API — Webhooks

Webhooks push session and CDR updates to your endpoint so you don't have to poll. One webhook of each type can be registered per API key.

Webhook types

Managing webhooks

Endpoints under /api/v1/webhooks (permissions webhook:read / webhook:manage):

# Register or update (upsert by type)
curl -s -X PUT \
  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
  -d '{ "type": "SESSION", "url": "https://your-backend.example.com/cpms/sessions" }' \
  "https://<host>/api/v1/webhooks"

# List registered webhooks
curl -s -H "x-api-key: $API_KEY" "https://<host>/api/v1/webhooks"

# Remove
curl -s -X DELETE -H "x-api-key: $API_KEY" \
  "https://<host>/api/v1/webhooks?type=SESSION"

Delivery contract

For each event, the backbone sends:

PUT {your-url}/{resourceId}
Authorization: <the API key that registered the webhook>
Content-Type: application/json

<SessionDto | CdrDto>

Notes:

• The resource ID is appended to your URL — register https://.../cpms/sessions and you receive PUT https://.../cpms/sessions/{sessionId}.
• The body is the same DTO the corresponding GET endpoint returns, so a PUT-shaped ingest endpoint can be idempotent by ID.
• Authenticate incoming deliveries by comparing the Authorization header against the registered key.

sequenceDiagram
    participant CPO as CPO Backbone
    participant You as Your endpoint

    Note over CPO: session updated / CDR created
    CPO->>You: PUT /cpms/sessions/{id}<br/>Authorization: <api key>
    You-->>CPO: 2xx (any response body ignored)
    Note over CPO: non-2xx or timeout →<br/>logged and dropped, no retry

Semantics you must design for

• Fire-and-forget. Deliveries are not retried; a failed delivery is logged server-side and dropped. Reconcile periodically with POST /sessions/rsql-list / POST /cdrs/rsql-list if you need guaranteed completeness.
• At-most-once, unordered. SESSION fires on every lifecycle event; treat deliveries as idempotent upserts keyed by id + lastUpdate rather than counting events.
• Timeout-bound. Your endpoint must respond within the configured delivery timeout; do heavy processing asynchronously after acknowledging.

Related

• Session Flows — where webhooks fit in the session lifecycle
• Authentication — key formats, legacy deprecation