---
title: "Session Lifecycle Webhooks — AVCodex Docs"
description: "Session Lifecycle Webhooks — AVCodex documentation for AV integrators, programmers, and ops teams."
lang: en
json-ld:
---

[](/)

Solutions

[Pricing](/pricing)[The Signal](/blog)[Resources](/resources)

Learn

[Free AI Assessment](/scorecard)[Get Started →](/pricing)

[Documentation Home](/docs)

Guides 

Getting Started

-   [The Alchemist Copilot](/docs/guides/the-alchemist-copilot)
-   [Choosing a Model](/docs/guides/choosing-a-model)
-   [Skills & Templates](/docs/guides/skills-and-templates)
-   [Pricing & Usage](/docs/guides/pricing-and-usage)
-   [Understanding Tokens](/docs/guides/understanding-tokens)
-   [Maximize AVCodex Capabilities](/docs/guides/maximize-avcodex-capabilities)

Knowledge & Memory

-   [How Knowledge Sources Work](/docs/guides/how-knowledge-sources-work)
-   [Knowledge Retrieval Settings](/docs/guides/knowledge-retrieval-settings)
-   [User Memory](/docs/guides/user-memory)
-   [Consumer Brain](/docs/guides/consumer-brain)

Agent Capabilities

-   [Image Recognition](/docs/guides/image-recognition)
-   [Image Generation](/docs/guides/image-generation)
-   [Video Generation](/docs/guides/video-generation)
-   [Deep Research and Deep Thinking](/docs/guides/deep-research-and-deep-thinking)
-   [Heartbeat (Proactive AI Outreach)](/docs/guides/heartbeat-proactive-ai-outreach)
-   [Database Connections](/docs/guides/database-connections)
-   [Agent-to-Agent Links](/docs/guides/agent-to-agent-links)
-   [Message Tagging](/docs/guides/message-tagging)
-   [Lead Generation Forms](/docs/guides/lead-generation-forms)
-   [Multilingual Apps](/docs/guides/multilingual-apps)
-   [Understanding Evaluations](/docs/guides/understanding-evaluations)

Design & Experience

-   [Style Studio](/docs/guides/style-studio)
-   [Component Studio](/docs/guides/component-studio)
-   [HQ Profile](/docs/guides/hq-profile)
-   [Multiplayer Chat](/docs/guides/multiplayer-chat)
-   [Circles](/docs/guides/circles)
-   [Desktop Agent](/docs/guides/desktop-agent)

Voice & Phone

-   [Phone Numbers](/docs/guides/phone-numbers)
-   [Outbound Calling](/docs/guides/outbound-calling)
-   [Voice Cloning](/docs/guides/voice-cloning)

Publish & Share

-   [Embed Chat Widget](/docs/guides/embed-chat-widget)
-   [Custom Domains](/docs/guides/custom-domains)
-   [PWA Installation](/docs/guides/pwa-installation)
-   [AVCodex Sites](/docs/guides/avcodex-sites)
-   [Embed on Kajabi](/docs/guides/embed-on-kajabi)
-   [How to Use AVCodex with Claude Code](/docs/guides/how-to-use-avcodex-with-claude-code)

Monetization & Access

-   [Selling Access](/docs/guides/selling-access)
-   [Consumer Monetization](/docs/guides/consumer-monetization)
-   [Access Control](/docs/guides/access-control)
-   [Bring Your Own Auth](/docs/guides/bring-your-own-auth)
-   [Clever SSO for Schools](/docs/guides/clever-sso-for-schools)

Analytics & Operations

-   [Analytics & Chat History](/docs/guides/analytics-and-chat-history)
-   [Performance Dashboard](/docs/guides/performance-dashboard)
-   [Programmatic Usage Stats](/docs/guides/programmatic-usage-stats)
-   [Session Lifecycle Webhooks](/docs/guides/session-lifecycle-webhooks)
-   [Audit Logs](/docs/guides/audit-logs)

Teams & White-Label

-   [Team Management](/docs/guides/team-management)
-   [Enterprise Whitelabel](/docs/guides/enterprise-whitelabel)

Alchemist Platform

-   [Alchemist Tickets](/docs/guides/alchemist-tickets)
-   [Alchemist Getting Started](/docs/guides/alchemist-getting-started)
-   [Alchemist Working with Tickets](/docs/guides/alchemist-working-with-tickets)
-   [Alchemist Local Development](/docs/guides/alchemist-local-development)

Alchemist Operations

-   [Alchemist Environment Variables](/docs/guides/alchemist-environment-variables)
-   [Alchemist Deploys and Domains](/docs/guides/alchemist-deploys-and-domains)
-   [Alchemist Self-Healing](/docs/guides/alchemist-self-healing)

Alchemist API & Automation

-   [Alchemist API Keys](/docs/guides/alchemist-api-keys)
-   [Alchemist MCP Server](/docs/guides/alchemist-mcp-server)
-   [Alchemist Pipeline Configuration](/docs/guides/alchemist-pipeline-configuration)
-   [Alchemist Pipeline Permutations](/docs/guides/alchemist-pipeline-permutations)

Developer Platform

-   [Building Custom MCP Servers](/docs/guides/building-custom-mcp-servers)
-   [Consumer OAuth for Custom MCP Servers](/docs/guides/consumer-oauth-for-custom-mcp-servers)

AVCodex MCP Server

-   [Overview](/docs/guides/overview)
-   [MCP Reference](/docs/guides/mcp-reference)
-   [Setup & Installation](/docs/guides/setup-and-installation)
-   [Authentication](/docs/guides/authentication)
-   [Tools Reference](/docs/guides/tools-reference)
-   [Common Workflows](/docs/guides/common-workflows)
-   [Rate Limits](/docs/guides/rate-limits)

Custom Actions 

Pro Actions 

API 

Builder API 

Agentic Commerce (ACP) 

Integrations 

[Docs](/docs)/ Guides / Analytics & Operations 

# Session Lifecycle Webhooks

Last updated · MAR 2026 · [Read as Markdown](/docs/guides/session-lifecycle-webhooks.md)

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# ](#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# ](#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# ](#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# ](#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# ](#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# ](#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# ](#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.\*

Was this helpful? 

[Edit this page →](#)

[

Previous

Programmatic Usage Stats

](/docs/guides/programmatic-usage-stats)[

Next

Audit Logs

](/docs/guides/audit-logs)

On this page

-   [When to use session webhooks](#when-to-use-session-webhooks)
-   [Configure the webhook](#configure-the-webhook)
-   [Send a test event](#send-a-test-event)
-   [Payload shape](#payload-shape)
-   [The QR code use case](#the-qr-code-use-case)
-   [Verifying the signature](#verifying-the-signature)
-   [Delivery behavior](#delivery-behavior)

[](/)

The AI platform built exclusively for professional AV. Build, deploy, and sell AI tools that understand your industry.

### Platform

-   What You Can Build
-   Templates
-   [Pricing](/pricing)

### Services

-   [Done-For-You](/pricing)
-   [Academy](/academy)
-   [Contact](/contact)

### Company

-   About
-   [The Signal](/blog)
-   [Docs](/docs)
-   [LinkedIn](#)

© 2026 AVCodex. A Future Ready Holdings Inc. product. SOC 2 Type II Certified · HIPAA Compliant