Session Lifecycle Webhooks

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.

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.

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.

Both event types share the same envelope.

{
  "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:

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

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.

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.

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.*