Webhooks
VoisX uses webhooks in both directions:
- Workflow webhooks (inbound). Another system, such as your CRM, form tool or backend, sends an HTTP POST to a URL that starts one of your workflows.
- Alert webhooks (outbound). VoisX sends an HTTP POST to your endpoint when an alert rule in your project fires.
- Conversation events (outbound). VoisX sends an HTTP POST to your endpoint when a call starts or ends, or a transcript is ready. See Conversation events.
Every outbound request is signed, so your endpoint can check that it came from VoisX. See Verify signatures.
Workflow webhooks
Get a webhook URL
- Open the workflow and go to the Triggers tab.
- Choose Webhook and click Add trigger.
- Copy the URL. It is shown only once.
The URL has this form:
https://<your console address>/api/webhooks/<secret token>
Use the URL exactly as the console shows it. It points at the data region where the workflow lives.
The secret token in the URL is the only credential. Anyone who has the URL can start the workflow. Store it like a password, keep it out of client-side code, and rotate it if it leaks.
Send a request
Send a POST with a JSON object as the body and Content-Type: application/json. The body is optional. No other headers are needed.
- cURL
- Node.js
- Python
curl -X POST "$VOISX_WEBHOOK_URL" \
-H "Content-Type: application/json" \
-d '{"lead_id": "L-1042", "name": "Asha Rao", "phone": "+919800000000"}'
const res = await fetch(process.env.VOISX_WEBHOOK_URL, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ lead_id: "L-1042", name: "Asha Rao", phone: "+919800000000" }),
});
const result = await res.json();
console.log(result.response);
import os
import requests
res = requests.post(
os.environ["VOISX_WEBHOOK_URL"],
json={"lead_id": "L-1042", "name": "Asha Rao", "phone": "+919800000000"},
timeout=300,
)
res.raise_for_status()
print(res.json()["response"])
The JSON body becomes the input of the run, so the workflow's first steps can read its fields.
Response
The request waits until the run finishes, then returns the result:
{
"ok": true,
"session_id": "6f1c2a3e-8a7b-4c1d-9e2f-0a1b2c3d4e5f",
"response": "Lead L-1042 qualified and booked for Tuesday 10:00."
}
| Field | Description |
|---|---|
ok | true when the run finished, or paused at a step that waits for a person, such as Human Handoff. |
session_id | The run's session ID. Use it to find the run on the workflow's Runs tab. |
response | The final output of the workflow. |
Because the call stays open for the length of the run, set a generous client timeout. For long workflows, such as ones that place phone calls, use a scheduled trigger instead.
Errors
| Status | Meaning | What to do |
|---|---|---|
402 | The organization doesn't have enough credit to start a run. | Add credits, then retry. |
403 | Your plan doesn't include this feature. | Check your plan. |
404 | The URL is wrong, the trigger was deleted or rotated, or the trigger is paused. | Check the URL and that the trigger is Active. |
429 | Your organization already has the maximum number of runs in progress. | Retry later with backoff. |
500 | The workflow failed. | Check the run on the Runs tab. |
503 | Runs are temporarily unavailable. | Retry later with backoff. |
504 | The run reached your plan's maximum run time. | Shorten the workflow, or use a scheduled trigger. |
VoisX doesn't retry a failed webhook call for you. If your system needs delivery guarantees, retry from your side on 429, 503 and network errors.
Rotate or pause
- Rotate webhook URL issues a new URL. The old one stops working immediately, so update the calling system right away.
- The Active switch pauses the trigger. While paused, calls return
404. - Delete trigger removes the URL for good.
Rotations appear in the project's audit log.
Alert webhooks
Alert rules notify you when something goes wrong in a project's agents. A rule can notify by email, Slack or webhook.
Create an alert rule
- In your project, open Analytics (under Observe).
- In Alert rules, click New rule.
- Choose a trigger:
- Error rate threshold: fires when the share of error events over a time window (5–1440 minutes) is at or above a percentage (1–100).
- Single critical error: fires on any single error.
- Under Notify via, choose Webhook and enter your endpoint URL.
- Set a Cooldown in minutes, the minimum time between two firings of the rule (default 30).
- Click Create rule.
Alert rules are available on plans that include alerts.
Payload
VoisX sends a POST with a JSON body:
{
"id": "evt_5f0c2d9a8b7e4c1d9e2f0a1b2c3d4e5f",
"type": "alert.fired",
"rule_id": 12,
"project_id": 345,
"subject": "Error rate alert: project 345",
"message": "Error rate over the last 15 minutes: 24.0% (12/50 events), above the 20% threshold.",
"fired_at": "2026-10-05T09:30:00.000000+00:00"
}
| Field | Description |
|---|---|
id | A unique ID for this alert. |
type | Always alert.fired. |
rule_id | The alert rule that fired. |
project_id | The project the rule belongs to. |
subject | A one-line summary. |
message | Details of what triggered the alert. |
fired_at | When the alert fired, in ISO 8601 UTC. |
The wording of subject and message may change. Route alerts on rule_id and project_id, not on the text.
Signing secret
Each webhook rule signs its requests with its own secret. To see it, open Analytics, find the rule under Alert rules and click Show secret. Use it to verify the signature of every request.
Rotate issues a new secret. The next alert is signed with it, and the old one stops verifying at once, so update your endpoint right away.
Delivery
Alerts are delivered, retried and signed as described in Outbound delivery. The X-VoisX-Event header is alert.fired.
Conversation events
Add a webhook endpoint in Settings → Webhooks to receive call.started, call.ended and transcript.ready for every conversation in the project. See Conversation events for the payloads.
Outbound delivery
Alert webhooks and conversation events are sent the same way.
Headers
Each request is a POST with a JSON body and these headers:
| Header | Description |
|---|---|
Content-Type | application/json. |
User-Agent | VoisX-Webhooks/1.0. |
X-VoisX-Event | The event type, such as alert.fired or call.ended. |
X-VoisX-Delivery | A unique ID for this delivery. It stays the same when the request is retried, so use it to ignore duplicates. |
X-VoisX-Timestamp | When this attempt was sent, in Unix seconds. |
X-VoisX-Signature | v1= followed by the hex HMAC-SHA256 of <X-VoisX-Timestamp>.<raw body>, keyed with the signing secret. See Verify signatures. |
Delivery and retries
- Your endpoint must answer with a
2xxstatus within 10 seconds. - If your endpoint times out, can't be reached, or answers
408,425,429or any5xxstatus, VoisX retries the request up to 5 times: after about 30 seconds, 2 minutes, 10 minutes, 30 minutes and 1 hour. ARetry-Afterheader of up to one hour is respected. - Any other status, such as
400,401or404, is final. Redirects aren't followed. - Each retry is signed again, with a new
X-VoisX-Timestamp, using the endpoint's current secret. - A retry can arrive after a newer event. Order events by their time field (
fired_atorcreated_at), and skip aX-VoisX-Deliveryvalue you have already handled. - The URL must use
https://and point at a public address. Private, loopback and link-local addresses are rejected when you save it.
Best practices
- Answer quickly and do slow work in the background.
- Treat every incoming payload as untrusted input and validate the fields you use.
- Verify the signature of every outbound request before you act on it.
- Keep webhook URLs, tokens and signing secrets in a secrets store, not in source code.