Webhooks

A flow with a webhook URL posts JSON to it while each session runs and once when it ends.

#Before you begin

You need:

• A public HTTPS endpoint on your server that accepts POST requests.

#Set the webhook URL

Open the flow's Webhook tab in the dashboard and enter your URL. To set it from your server instead, update the flow:

1await voxio.flows.update(flowKey, { webhookUrl: "https://example.com/voxio" });

#Receive the events

Accept the POST, answer straight away, and do slow work afterwards. This Express handler saves the transcript when a session finishes:

1app.post("/voxio", express.json({ limit: "2mb" }), (req, res) => {
2  const { status, session_id } = req.body;
3
4  if (status === "finished") {
5    const history = req.body["session-data"]?.state?.conversation_history ?? [];
6    saveTranscript(session_id, history);
7  }
8
9  res.sendStatus(200);
10});

Use session_id to tie each webhook to the browser session or call that produced it.

#Payload

Every post has this shape:

1{
2  "status": "finished",
3  "session_id": "8b1f…",
4  "session-data": {
5    "state": {
6      "conversation_history": [
7        { "role": "user", "content": "Hi" },
8        { "role": "assistant", "content": "Hello! How can I help?" }
9      ]
10    }
11  },
12  "responses": [
13    { "node": "reply", "out": { "speak": "…", "hangup": false } }
14  ]
15}

responses holds what each workflow step produced on that turn. Every key your workflow outputs arrives there, not only speak, so you can send structured data such as a score, a booking or a lead straight to your server.

#Statuses

#Next steps

• Sessions and usage: read a session again later.
• Flows: make the workflow output the data you need.