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.
Choose a starting point
- Run follow-up work after a conversation: subscribe to Session ended. 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 for the voice connection’s timing and metadata.
- Track releases: receive Environment published events with the before-and-after version IDs.
- Build the receiver: configure the matching endpoint, then verify incoming requests before processing their payloads.
Choose an event family
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 define the payloads; a call ending and a session ending describe different boundaries.
Connect and verify your receiver
Configure the endpoint in the right scope
Add your receiver’s URL in project Webhooks settings or Organization settings. Choose the events your integration handles and wait for Saved.
Verify requests with that endpoint’s secret
Copy Webhook secret from the same settings form and use Svix signature verification in your receiver. Verify the original request body before parsing it. Secret rotation gives you 24 hours to replace the old secret.
Route each event to its handler
Check type, then read the session/call payload or organization payload. Handle optional session 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, with REST, Streaming or WebSocket.