Webhooks API

Webhooks push events to your server as they happen — conversations starting and ending, agents activating, crawls completing — so you never have to poll. Reading is gated on webhooks.read; writing on webhooks.write.

Supported events

  • conversation.started
  • conversation.ended
  • conversation.evaluated — goal criteria scored
  • widget.activated / widget.paused — agent status transitions
  • widget.crawl_completed

Unknown event names are silently dropped from a subscription, so stick to this list (also returned as supported_events by the list endpoint).

List & create endpoints

GET  /api/v1/rest/webhooks
POST /api/v1/rest/webhooks
{
  "url":    "https://example.com/hooks/seny",
  "events": ["conversation.ended", "conversation.evaluated"],
  "description": "CRM sync"
}

The endpoint object is { id, url, events, active, description, created_at, updated_at }. The create response additionally includes the signing_secret — shown only once; store it to verify payload signatures. URLs must be https:// and resolve to a public host.

Get, update, delete

GET    /api/v1/rest/webhooks/:id
PATCH  /api/v1/rest/webhooks/:id     # { url?, events?, description?, active? }
DELETE /api/v1/rest/webhooks/:id

Enable or disable an endpoint by PATCHing { "active": true | false }. To rotate a secret, delete the endpoint and create a fresh one (a new secret is minted on create).

Test an endpoint

POST /api/v1/rest/webhooks/:id/test

Sends a conversation.ended test ping to your URL and returns { ok: true }; check the deliveries list for the response your server gave.

Deliveries

GET /api/v1/rest/webhooks/:id/deliveries   ?success=true|false &limit= &offset=

Recent delivery attempts, newest first (limit max 200). Each row: { id, event_type, payload, status_code, response_body, duration_ms, success, created_at }. To retry a failed event, fix your receiver — subsequent events deliver normally; there is no per-delivery resend.

Full schemas are in the OpenAPI reference.