Workflow webhooks

A webhook trigger lets another system start a workflow, for example when a form is submitted or an order is placed. You post JSON to the workflow's webhook URL and get the workflow's answer back.

Webhook URLs do not use an API key. The secret token in the URL is the credential, so treat the whole URL like a password. Call it from your server or another backend system, never from a web page.

Get a webhook URL

1. Sign in at app.voisx.ai and open your project.
2. Go to Workflows and open the workflow. Save it if it is new.
3. In the Triggers panel, add a Webhook trigger.
4. Copy the Webhook URL and use it exactly as the console shows it. Its path is /api/webhooks/{token}, on your region's address.

warning

The console shows the full URL only once, right after you create or rotate it. After that you only see the last four characters. If you lose it, rotate it to get a new one.

To stop the URL from working for a while, switch the trigger off in the Triggers panel. To replace it, select the rotate icon next to the URL. The old URL stops working immediately.

Trigger a workflow

POST/api/webhooks/{token}

Runs the workflow and waits for it to finish. The request body becomes the workflow's input message, as JSON text. Each call starts a new run with its own session.

Runs are billed as workflow runs. Your plan must include workflows. See voisx.ai/pricing.

Path parameters

tokenstringrequired

The secret token from the webhook URL.

Body

Any JSON object. A body that is not a JSON object, such as a list, returns 422. If you send no body or an empty object, the workflow gets the message webhook trigger.

Response fields

okbooleanoptional

true when the run finished or paused for a person to act.

session_idstringoptional

The run's session ID. Use it to find the run in the console.

responsestringoptional

The workflow's last message. Empty when the workflow produced no text.

Responses

200

The run finished, or paused at a step that waits for a person.

402

Your organization has no active subscription or not enough credit.

403

Your plan does not include workflows or a feature the workflow uses.

404

The token is wrong, the trigger is switched off, or the workflow was deleted.

422

The body is not a JSON object.

429

Your organization is already running as many workflows at once as your plan allows.

500

The workflow failed. The run and its error show in the console.

503

The workflow service is temporarily unavailable.

504

The run took longer than your plan allows.

cURL

curl -X POST "$VOISX_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "A-1042",
    "customer_email": "asha@example.com"
  }'

Node.js

const res = await fetch(process.env.VOISX_WEBHOOK_URL, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    order_id: "A-1042",
    customer_email: "asha@example.com",
  }),
});
const run = await res.json();

Python

import os
import requests

res = requests.post(
    os.environ["VOISX_WEBHOOK_URL"],
    json={"order_id": "A-1042", "customer_email": "asha@example.com"},
    timeout=300,
)
run = res.json()

200 OK

{
  "ok": true,
  "session_id": "0b9d6c3e-55a1-4f0e-8a3b-2f6e7c1d9a40",
  "response": "Order A-1042 is confirmed. A summary was sent to asha@example.com."
}

404 Not Found

{
  "detail": "Trigger not found or inactive."
}

tip

The request stays open until the run ends, which can take a while for long workflows. Set your HTTP client's timeout to a few minutes.