curl --request POST \
--url https://api.usenexio.com/api/v1/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://hooks.example.com/nexio",
"events": [
"run.completed",
"run.failed",
"run.cancelled"
],
"description": "Production run callbacks",
"payload_mode": "full",
"auth_token": "gw_example_token"
}
'import requests
url = "https://api.usenexio.com/api/v1/webhooks"
payload = {
"url": "https://hooks.example.com/nexio",
"events": ["run.completed", "run.failed", "run.cancelled"],
"description": "Production run callbacks",
"payload_mode": "full",
"auth_token": "gw_example_token"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://hooks.example.com/nexio',
events: ['run.completed', 'run.failed', 'run.cancelled'],
description: 'Production run callbacks',
payload_mode: 'full',
auth_token: 'gw_example_token'
})
};
fetch('https://api.usenexio.com/api/v1/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "2f7c1b9e-4a3d-4e8b-9c61-0d5a7e3f8b12",
"url": "https://hooks.example.com/nexio",
"environment": "live",
"events": [
"run.completed",
"run.failed",
"run.cancelled"
],
"description": "Production run callbacks",
"active": true,
"auth_token_configured": true,
"webhook_version": "2026-03-22",
"payload_mode": "full",
"created_at": "2026-09-23T14:02:11Z",
"secret": "whsec_example000000000000000000000000000000000000000000000000000000000"
}Create webhook endpoint
Register an HTTPS endpoint for run events and receive its signing secret once.
curl --request POST \
--url https://api.usenexio.com/api/v1/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://hooks.example.com/nexio",
"events": [
"run.completed",
"run.failed",
"run.cancelled"
],
"description": "Production run callbacks",
"payload_mode": "full",
"auth_token": "gw_example_token"
}
'import requests
url = "https://api.usenexio.com/api/v1/webhooks"
payload = {
"url": "https://hooks.example.com/nexio",
"events": ["run.completed", "run.failed", "run.cancelled"],
"description": "Production run callbacks",
"payload_mode": "full",
"auth_token": "gw_example_token"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://hooks.example.com/nexio',
events: ['run.completed', 'run.failed', 'run.cancelled'],
description: 'Production run callbacks',
payload_mode: 'full',
auth_token: 'gw_example_token'
})
};
fetch('https://api.usenexio.com/api/v1/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "2f7c1b9e-4a3d-4e8b-9c61-0d5a7e3f8b12",
"url": "https://hooks.example.com/nexio",
"environment": "live",
"events": [
"run.completed",
"run.failed",
"run.cancelled"
],
"description": "Production run callbacks",
"active": true,
"auth_token_configured": true,
"webhook_version": "2026-03-22",
"payload_mode": "full",
"created_at": "2026-09-23T14:02:11Z",
"secret": "whsec_example000000000000000000000000000000000000000000000000000000000"
}Authorizations
Send the key as Authorization: Bearer <key>. Two kinds of key exist.
Organization keys are issued in the portal (Settings, then API keys),
each bound to one environment, shaped nx_<environment slug>_<64 hex>. They carry
no capabilities and pass every capability check, with one exception:
routes under /records, /actions, /operations,
/api/v1/engines/{id}/opportunities, /api/v1/graph and
/api/v1/catalog/documents accept an
organization key only when its environment is live, and refuse any
other with 403 scoped_key_required. Revocation takes effect within 60
seconds.
Scoped keys are issued by Nexio on request, shaped
nxsk_v1_<24 hex key id>_<43 character secret>. Each is bound to one
org, one environment, a set of engines and a set of capabilities. A
malformed, unknown or revoked nxsk_ key fails with 401 and is never
retried as an organization key. Revocation takes effect on the next
request. A scoped key without a route's capability gets 403
insufficient_capability; a scoped key not bound to the engine gets 403
engine_binding_forbidden.
Key-grantable capabilities: engines:read, runs:write, runs:read,
runs:defensibility:read, runs:test, catalog:read,
catalog:documents:read, webhooks:manage, conversations:use,
conversations:export, records:read, records:opportunities:run,
actions:write, actions:read, graph:read, records:analyze.
Routes that accept organization keys only (every scoped key gets 403
insufficient_capability): environment management, engine create,
update, configuration and publish, and conversation instance
authoring. Each operation description names the capability a scoped
key needs.
Body
HTTPS endpoint URL to receive webhook deliveries. At most 2048 UTF-8 bytes after trimming.
Event types to subscribe to.
1run.completed, run.failed, run.cancelled, run.superseded Optional human-readable description, at most 256 UTF-8 bytes after trimming.
Whether the endpoint starts active. Defaults to true.
Optional bearer token included as Authorization: Bearer <token>
on outbound deliveries. At most 1024 UTF-8 bytes after trimming.
An empty value sets no token.
Delivery body shape. Defaults to full. thin delivers only run
identifiers and terminal status (body stays under 1 KB); fetch the
full run with GET /api/v1/runs/{run_id}.
full, thin Response
Endpoint created. Secret is included only in this response.
Endpoint identifier.
Delivery target URL.
Environment this endpoint receives events from.
test, live Subscribed event types.
run.completed, run.failed, run.cancelled, run.superseded Whether the endpoint is active.
Whether an auth token is set (the token value is never returned).
Payload version string (e.g. 2026-03-22).
Delivery body shape. full (default) carries the complete run; thin carries only run identifiers and terminal status.
full, thin RFC 3339 creation timestamp.
HMAC-SHA256 signing secret (whsec_...). Displayed only once.
Store it securely.
Human-readable description.
Exact instant when the previous secret stops being valid.
Present only while the system has deactivated the endpoint after a consecutive dead-letter streak. Cleared on re-enable.
Actor that deactivated the endpoint (system for the automatic dead-letter streak deactivation). Present only while deactivated.
Why the endpoint was deactivated, including the triggering delivery ID. Present only while deactivated.
RFC 3339 last-update timestamp. Absent on the create response.