Initial Setup

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

Event	Trigger	Notes
`session.ended`	The 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.ended`	The call has ended.	Call sessions only. Text sessions never produce this event.
`recording.ready`	The call recording finished processing (success or failure).	Call sessions only. Gates `session.finalized` — finalization waits for recording processing (with a timeout backstop). Carries a short-lived `recordingUrl` on success; the only event that reports a failed recording.
`session.finalized`	Everything is done for this session.	Always the last event for a session. Combines the data from every other event into one body, including the conversation transcript (`messages`) and, for recorded calls, the `recordingUrl`.

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"]
    }
  }'

string

required

HTTPS endpoint that accepts POST + JSON.

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.

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.

API Documentation

V1 Developer API

API Endpoints

Post Webhooks

Integration APIs

Deprecated APIs

Event types

Configure

Subscribing to multiple events

Delivery semantics

Next steps

Webhook payloads

Update agent

​Event types

​Configure

​Subscribing to multiple events

​Delivery semantics

​Next steps

Webhook payloads

Update agent

Event types

Configure

Subscribing to multiple events

Delivery semantics

Next steps