Skip to main content

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​

  1. Open the workflow and go to the Triggers tab.
  2. Choose Webhook and click Add trigger.
  3. 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.

warning

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 -X POST "$VOISX_WEBHOOK_URL" \
-H "Content-Type: application/json" \
-d '{"lead_id": "L-1042", "name": "Asha Rao", "phone": "+919800000000"}'

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."
}
FieldDescription
oktrue when the run finished, or paused at a step that waits for a person, such as Human Handoff.
session_idThe run's session ID. Use it to find the run on the workflow's Runs tab.
responseThe 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​

StatusMeaningWhat to do
402The organization doesn't have enough credit to start a run.Add credits, then retry.
403Your plan doesn't include this feature.Check your plan.
404The URL is wrong, the trigger was deleted or rotated, or the trigger is paused.Check the URL and that the trigger is Active.
429Your organization already has the maximum number of runs in progress.Retry later with backoff.
500The workflow failed.Check the run on the Runs tab.
503Runs are temporarily unavailable.Retry later with backoff.
504The 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​

  1. In your project, open Analytics (under Observe).
  2. In Alert rules, click New rule.
  3. 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.
  4. Under Notify via, choose Webhook and enter your endpoint URL.
  5. Set a Cooldown in minutes, the minimum time between two firings of the rule (default 30).
  6. 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"
}
FieldDescription
idA unique ID for this alert.
typeAlways alert.fired.
rule_idThe alert rule that fired.
project_idThe project the rule belongs to.
subjectA one-line summary.
messageDetails of what triggered the alert.
fired_atWhen 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:

HeaderDescription
Content-Typeapplication/json.
User-AgentVoisX-Webhooks/1.0.
X-VoisX-EventThe event type, such as alert.fired or call.ended.
X-VoisX-DeliveryA unique ID for this delivery. It stays the same when the request is retried, so use it to ignore duplicates.
X-VoisX-TimestampWhen this attempt was sent, in Unix seconds.
X-VoisX-Signaturev1= 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 2xx status within 10 seconds.
  • If your endpoint times out, can't be reached, or answers 408, 425, 429 or any 5xx status, VoisX retries the request up to 5 times: after about 30 seconds, 2 minutes, 10 minutes, 30 minutes and 1 hour. A Retry-After header of up to one hour is respected.
  • Any other status, such as 400, 401 or 404, 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_at or created_at), and skip a X-VoisX-Delivery value 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.
Was this page helpful?