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

# Webhooks

> Receive session, call, project and Environment events in your systems. Choose event subscriptions, configure an endpoint and verify incoming requests.

## Overview

Webhooks send an HTTP POST with event metadata to a URL you configure. Use them to start follow-up work after a customer conversation, track call activity or record changes to your projects and Environments.

Voiceflow has two webhook scopes: **Session lifecycle** in a project’s **Settings → Webhooks**, and **Organization event webhooks** in dashboard **Settings → Organization**. Each has its own endpoint URL and signing secret.

Project Webhooks settings showing a configured endpoint, selected call and session events, and a masked signing secret — In project Settings → Webhooks, choose events and copy the signing secret for your receiver.

## Choose a starting point

- **Run follow-up work after a conversation:** subscribe to [Session ended](/docs/api-reference/webhooks/session-lifecycle#runtime-session-end). An idle session ends on its timeout; closing the chat widget does not end it immediately.
- **Track a voice call:** use [Call started and Call ended](/docs/api-reference/webhooks/session-lifecycle#call-events) for the voice connection’s timing and metadata.
- **Track releases:** receive [Environment published](/docs/api-reference/webhooks/org-events#organization-project-environment-published) events with the before-and-after version IDs.
- **Build the receiver:** [configure the matching endpoint](/docs/api-reference/webhooks/session-lifecycle#configuring-your-webhook), then [verify incoming requests](/docs/api-reference/webhooks/overview#receiving-events) before processing their payloads.

## Choose an event family

<a id="event-families" />

| Event family | What it reports | Where you configure it |
| --- | --- | --- |
| [Session lifecycle](/docs/api-reference/webhooks/session-lifecycle) | Conversations and voice calls starting or ending, with project, user and session/call metadata. | The project’s **Settings → Webhooks**. |
| [Organization events](/docs/api-reference/webhooks/org-events) | Projects being created or deleted, and Environments being created, published, merged or deleted. | Dashboard **Settings → Organization**. |

Choose **Listen for all events** for the scope’s complete catalog, or **Listen for specific events** to select individual events or a category. The [event references](/docs/api-reference/webhooks/session-lifecycle#events) define the payloads; a call ending and a session ending describe different boundaries.

## Connect and verify your receiver

<a id="receiving-events" />

### 1. Configure the endpoint in the right scope

Add your receiver’s URL in [project Webhooks settings](/docs/api-reference/webhooks/session-lifecycle#configuring-your-webhook) or [Organization settings](/docs/api-reference/webhooks/org-events#configuring-your-webhook-settings). Choose the events your integration handles and wait for **Saved**.

### 2. Verify requests with that endpoint’s secret

Copy **Webhook secret** from the same settings form and use [Svix signature verification](https://docs.svix.com/receiving/verifying-payloads/how) in your receiver. Verify the original request body before parsing it. [Secret rotation](/docs/api-reference/webhooks/org-events#verifying-requests-come-from-voiceflow) gives you 24 hours to replace the old secret.

### 3. Route each event to its handler

Check `type`, then read the [session/call payload](/docs/api-reference/webhooks/session-lifecycle#events) or [organization payload](/docs/api-reference/webhooks/org-events#supported-events). Handle [optional session fields](/docs/api-reference/webhooks/session-lifecycle#optional-fields) as nullable. For example, use `data.projectID` to distinguish projects sharing a receiver.

### Conversation streaming

Webhooks notify your backend about lifecycle and organization events. To send messages to an agent and render its responses during a conversation, use the [Agent runtime](/docs/api-reference/sections/running-agents), with REST, Streaming or WebSocket.
