Skip to main content
Webhooks allow you to receive real-time event notifications when calls and sessions start and end in Voiceflow, enabling seamless integration with your systems. This helps automate workflows, log call and session data, and trigger actions based on lifecycle events for both Twilio and web voice interactions. Add your webhook URL under Settings / Webhooks

​
Events

Phone calls will receive both the runtime.call.* events and the corresponding runtime.session.* events. Use type to differentiate which event you’re handling.
Voiceflow will send POST requests to your webhook URL on the following events.
Human-readable nameName
Call startedruntime.call.start
Call endedruntime.call.end
Session startedruntime.session.start
Session endedruntime.session.end

​
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)
{
  "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}
}

{
  "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. 
{
  "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}
}

{
  "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",
}

​
runtime.session.start

This event is sent when a new session is started for a user. 
{
  "type": "runtime.session.start",
  "data": {
    "userID": string,
    "projectID": string,
    "environmentID": string,
    "sessionID": string,
    "startTime": number // unix timestamp MS
  }
  "time": number // unix timestamp MS, event time
  "resource": string // project-{projectID}
}

{
  "type": "runtime.session.start",
  "data": {
    "environmentID": "6a15b5f6a85b1b570a8773cf",
    "projectID": "69f9fa36eeb8f50e7cfd2d5f",
    "sessionID": "6a15b6093f95e60007ec4e04",
    "startTime": 1779807753396,
    "userID": "g4dq75wr6asov6z571860xg0"
  },
  "resource": "project-69f9fa36eeb8f50e7cfd2d5f",
  "time": 1779807753433
}

​
runtime.session.end

This event is sent when a session ends. 
{
  "type": "runtime.session.end",
  "data": {
    "userID": string,
    "projectID": string,
    "environmentID": string,
    "sessionID": string,
    "startTime": number, // unix timestamp MS
    "endTime": number // unix timestamp MS
  }
  "time": number // unix timestamp MS, event time
  "resource": string // project-{projectID}
}

{
  "type": "runtime.session.end",
  "data": {
    "endTime": 1779807762998,
    "environmentID": "6a15b5f6a85b1b570a8773cf",
    "projectID": "69f9fa36eeb8f50e7cfd2d5f",
    "sessionID": "6a15b6093f95e60007ec4e04",
    "startTime": 1779807753396,
    "userID": "g4dq75wr6asov6z571860xg0"
  },
  "resource": "project-69f9fa36eeb8f50e7cfd2d5f",
  "time": 1779807763081
}

​
Platform Metadata

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

​
Twilio

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