Skip to main content
When an agent’s postSessionWebhook is configured, Pathors POSTs JSON to your URL whenever a subscribed lifecycle event fires. You choose which events trigger the webhook (multi-select); each event carries its own payload, identified by the top-level event field.

​
Event types

EventTriggerNotes
session.endedThe conversation has ended.Default for backwards compatibility. For call sessions, the call’s final status and duration may not be available yet at this moment.
call.endedThe call has ended.Call sessions only. Text sessions never produce this event.
session.finalizedEverything is done for this session.Combines the data from every other event into one body.
recording.readyThe call recording finished processing (success or failure).Call sessions only. Independent of session.finalized — may arrive before or after it. Carries a short-lived recordingUrl on success.

​
Configure

The webhook lives on the agent. Configure it via the agent settings UI, or programmatically via update-agent: 
curl -X PATCH https://api.pathors.com/v1/projects/{projectId}/agent \
  -H 'Authorization: Bearer <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "postSessionWebhook": {
      "url": "https://your-server.example.com/pathors-webhook",
      "events": ["session.ended", "session.finalized"]
    }
  }'
​
url
string
required
HTTPS endpoint that accepts POST + JSON.
​
headers
array
Optional. Custom HTTP headers sent to your endpoint along with Content-Type: application/json. Each entry is { "key": string, "value": string }. Use cases are up to you — e.g. an Authorization token to verify the source, or a routing identifier on a shared receiver.
​
events
array of string
Which lifecycle events fire the webhook. Defaults to ["session.ended"] when omitted, which preserves the pre-2026 single-event behavior.

​
Subscribing to multiple events

Subscribing to more than one event delivers one POST per event per session. Branch on the top-level event field — see the implementation example on the payloads page. 
{
  "events": ["session.ended", "call.ended", "session.finalized"]
}

​
Delivery semantics

  • session.finalized fires at most once per session — a CAS guard on the underlying database row dedupes it even under concurrent writes. The other events (session.ended, call.ended, recording.ready) are emitted per processing step and may be re-delivered (for example on internal retries); if you need exactly-once handling, dedupe on (sessionId, event).
  • No automatic retry. A non-2xx response from your endpoint is logged to webhook_logs but Pathors does not resend. If you need at-least-once, ingest from a queue you control.
  • Respond fast. Pathors waits for your response synchronously; long-running work belongs in a background job on your side.
  • Backwards compatibility. Configurations that pre-date the multi-event support omit events and behave as events: ["session.ended"]. Existing receivers do not need to change.

​
Next steps

Webhook payloads

Full payload schemas + receiver example.

Update agent

Set postSessionWebhook programmatically.