Webhook events

Below is the complete catalog of webhook events Saaya emits. Each event has a stable schema, a `version` field, and is delivered at-least-once with HMAC-SHA256 signing. Subscribe to as many or as few as you need.

Session events

• `session.started`, a new conversation has begun. Payload includes channel, agent id, version id, and metadata.
• `session.ended`, the conversation has closed. Payload includes duration, transcript url, sentiment summary, cost.
• `session.errored`, the session ended on an error. Payload includes the error code and the last meaningful turn.
• `session.escalated`, the agent handed off to a human. Payload includes the escalation reason.

{
  "id":      "evt_2N3rH...",
  "type":    "session.ended",
  "version": "2026-04-01",
  "data": {
    "sessionId":  "ses_…",
    "agentId":    "agt_…",
    "versionId":  "v_2026_04_27_a",
    "channel":    "voice",
    "durationMs": 184320,
    "transcriptUrl": "https://api.saaya.ai/api/v1/sessions/ses_…/transcript",
    "sentiment":   { "avg": 0.32, "min": -0.18, "max": 0.74 },
    "cost":        { "totalUsd": 0.0184 }
  },
  "createdAt": "2026-04-27T10:14:31Z"
}

Tool events

• `tool.called`, a tool was invoked. Payload includes tool name, input, output, duration.
• `tool.errored`, a tool returned a terminal error after retries. Payload includes the last error.

Agent events

• `agent.created`, a new agent was created.
• `agent.updated`, a draft version was minted.
• `agent.published`, a draft was promoted to production.
• `agent.rolledback`, production was reverted to a previous version.

Campaign events

• `campaign.created`, a new campaign was created.
• `campaign.started`, dispatch has begun.
• `campaign.paused`, dispatch was paused (manual or budget alert).
• `campaign.row.completed`, one row finished, across the full cascade if any.
• `campaign.completed`, all rows finished.

Knowledge base events

• `kb.upload.completed`, an upload finished indexing.
• `kb.upload.failed`, an upload failed validation or indexing.