> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pathors.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Initial Setup

> Configure your agent's webhook URL and pick which lifecycle events fire it.

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](/en/api-reference/v1/agent/update-agent):

```bash theme={null}
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"]
    }
  }'
```

<ParamField body="url" type="string" required>
  HTTPS endpoint that accepts POST + JSON.
</ParamField>

<ParamField body="headers" type="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.
</ParamField>

<ParamField body="events" type="array of string">
  Which lifecycle events fire the webhook. Defaults to `["session.ended"]` when omitted, which preserves the pre-2026 single-event behavior.
</ParamField>

## 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](/en/api-reference/webhook/payloads#implementation-example) on the payloads page.

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Webhook payloads" icon="code" href="/en/api-reference/webhook/payloads">
    Full payload schemas + receiver example.
  </Card>

  <Card title="Update agent" icon="pen" href="/en/api-reference/v1/agent/update-agent">
    Set `postSessionWebhook` programmatically.
  </Card>
</CardGroup>