# Session Lifecycle Webhooks

Receive signed HTTP events when consumers start or end a chat session, including the URL query params they arrived with.

---

Session webhooks send a signed HTTP POST to your own endpoint whenever a consumer starts or ends a chat session on your AVCodex app. This lets you track conversation starts and ends deterministically, without depending on the AI to call a custom action.

> **Note:** Session webhooks are the deterministic complement to query-param variables. Those variables let your agent pass attribution data to a custom action at the right moment in the conversation. Session webhooks give you the same data automatically, at session start, with no model involvement.

## When to use session webhooks

Use them when you need reliable, automatic notification that a session started or ended:

- Logging every session start to your analytics or CRM, no matter what the AI does.
- Binding a tokenized URL parameter (like `?room=BLDG4-CONF2`) to a session record in your system.
- Triggering a workflow when a user opens the chat.

For actions that depend on what happened in the conversation (a form submitted, a service requested, a truck roll approved), use custom actions instead. Those let the AI decide when to fire based on context.

## Configure the webhook

1. Open your app in the builder.
2. Go to **Access** in the left navigation.
3. Scroll to the **Session Webhooks** section.
4. Enter your endpoint URL. It must be `https://`.
5. Choose which events to receive: `session.created`, `session.ended`, `integration.tools_dropped`, `integration.tools_restored`, or any combination.
6. Click **Save**.

On first save, a signing secret is generated and shown **once**. Copy it immediately and store it somewhere secure, like an environment variable. You will not be able to retrieve it again. To replace it later, use the rotate button.

### Send a test event

After saving, click **Send test event**. A synthetic `session.created` payload flagged with `"test": true` is posted to your endpoint so you can confirm it receives and verifies the signature before relying on it in production.

## Payload shape

Both event types share the same envelope.

```json
{
  "event": "session.created",
  "applicationId": "550e8400-e29b-41d4-a716-446655440000",
  "sessionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "source": "web",
  "consumerId": "c3f8b2a0-1234-5678-abcd-ef0123456789",
  "externalId": "user-from-crm-456",
  "queryParams": [
    { "name": "room", "value": "BLDG4-CONF2" },
    { "name": "src", "value": "qr" }
  ],
  "startedAt": "2026-07-09T14:22:31.000Z",
  "timestamp": "2026-07-09T14:22:31.412Z"
}
```

For `session.ended`, the payload also includes `endedAt`:

```json
{
  "event": "session.ended",
  "endedAt": "2026-07-09T14:45:02.000Z"
}
```

## The QR code use case

This is the single most useful feature on this page for room-based AV support.

Put a QR code in each room encoding a URL with a room identifier: `https://support.yourdomain.com/?room=BLDG4-CONF2&src=qr`. When a user scans it and the session opens, the webhook fires with that room ID in `queryParams` before the user has typed anything.

That gives you:

- A room-level record of every support interaction, whether or not it became a ticket.
- Deflection data you can show a client at renewal: how many sessions happened in each room, and how many escalated.
- Heat mapping. The rooms generating the most sessions are the rooms with the real problems, which is usually not the rooms generating the most tickets.

## Verifying the signature

Always verify the signature before processing a payload. Compute the HMAC over the signed payload using your signing secret and compare it to the signature header using a constant-time comparison. Reject anything that does not match, and reject payloads with a stale timestamp to prevent replay.

## Delivery behavior

Respond `2xx` quickly and process asynchronously. Assume events may be delivered more than once and deduplicate on `sessionId` plus `event`.

*AVCodex · Your AV expertise. Amplified by AI.*