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

# Session lifecycle webhook

> Send events from your project's calls to your webhook.

Webhooks allow you to receive real-time event notifications when calls start and end in Voiceflow, enabling seamless integration with your systems. This helps automate workflows, log call data, and trigger actions based on call events for both Twilio and web voice interactions.

Add your webhook URL under **Settings / Webhooks**

## Events

Voiceflow will send POST requests to your webhook URL on the following events.

### `runtime.call.start`

This event is sent when the following call types are made:

* Twilio inbound / outbound / prototype-outbound call
* web widget voice call is made (including during testing on `creator.voiceflow.com`)

```typescript theme={null}
{
  "type": "runtime.call.start",
  "data": {
    "userID": string,
    "projectID": string,
    "environmentID": string, // alias of the environment the call ran against
    "startTime": number, // unix timestamp MS
    "platform": "twilio" | "web-voice",
    "metadata": object // depends on "platform"
  }
  "time": number // unix timestamp MS, event time
  "resource": string // project-{projectID}
}
```

Example `runtime.call.start` event:

```json theme={null}
{
  "type": "runtime.call.start",
  "data": {
    "userID": "+19876543210",
    "environmentID": "69f3df348d8088f34a622739",
    "projectID": "6772da2e485189279fa5b9da",
    "startTime": 1743563467788,
    "platform": "twilio",
    "metadata": {
      "callSid": "CA01ed76f14fee29c50f5de59400474006",
      "callType": "inbound",
      "userNumber": "+19876543210",
      "agentNumber": "+17782006110"
    }
  },
  "time": 1743563467874,
  "resource": "project-6772da2e485189279fa5b9da",
}
```

### `runtime.call.end`

This event is sent when a call is completed.

```typescript theme={null}
{
  "type": "runtime.call.end",
  "data": {
    "userID": string,
    "projectID": string,
    "environmentID": string, // alias of the environment the call ran against
    "startTime": number, // unix timestamp MS
    "endTime": number, // unix timestamp MS
    "endReason"?: string | undefined, // why the call ended, arbitrary string, common reasons include "hangup" "end trace" "twiml" "answering machine"
    "platform": "twilio" | "web-voice",
    "metadata": object // depends on "platform"
  }
  "time": number // unix timestamp MS
  "resource": string // project-{projectID}
}
```

Example `runtime.call.end` event:

```json theme={null}
{
  "type": "runtime.call.end",
  "data": {
    "userID": "+19876543210",
    "environmentID": "69f3df348d8088f34a622739",
    "projectID": "6772da2e485189279fa5b9da",
    "startTime": 1743563467788,
    "endTime": 1743563467834,
    "endReason": "hangup",
    "platform": "twilio",
    "metadata": {
      "callSid": "CA01ed76f14fee29c50f5de59400474006",
      "callType": "inbound",
      "userNumber": "+19876543210",
      "agentNumber": "+17782006110"
    },
    
  },
  "time": 1743563467874,
  "resource": "project-6772da2e485189279fa5b9da",
}
```

## Platform Metadata

Depending on `data.platform`, the metadata for the call will change.

### Twilio

```typescript theme={null}
"platform": "twilio",
"metadata": {
  "callSid": string // twilio call sid, can be used to check twilio logs
  "callType": "inbound" | "outbound" | "prototype-outbound",
  "userNumber": string // phone number of the user
  "agentNumber": string // phone number of the agent / bot
}
```

The *to* and *from* number depends on the type of call.

For example, for an `"inbound"` call, from is the `userNumber` and to is the `agentNumber`, while it is the inverse for `"outbound"`.

### web-voice

No additional metadata currently. In the future, this may include browser and geographic information.

```typescript theme={null}
"platform": "web-voice",
"metadata": { 
  // empty
}
```

## Best Practices

* Check `type` when evaluating response. There may be additional types of events in the future with a different shaped request body, as well as new properties and metadata.
* Check `data.platform` before evaluating `data.metadata`, for example it's possible that `data.metadata.callSid` doesn't exist because it's a `"web-voice"` call.
* You can check `data.projectID` if you want to share the same endpoint between different projects.