curl --request PATCH \
--url https://api.usenexio.com/api/v1/webhooks/{endpointID} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://api.example.com/nexio/webhooks/v2",
"active": true
}
'import requests
url = "https://api.usenexio.com/api/v1/webhooks/{endpointID}"
payload = {
"url": "https://api.example.com/nexio/webhooks/v2",
"active": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({url: 'https://api.example.com/nexio/webhooks/v2', active: true})
};
fetch('https://api.usenexio.com/api/v1/webhooks/{endpointID}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "<string>",
"environment": "test",
"events": [
"run.completed"
],
"active": true,
"auth_token_configured": true,
"webhook_version": "<string>",
"payload_mode": "full",
"created_at": "2023-11-07T05:31:56Z",
"description": "<string>",
"previous_secret_expires_at": "2023-11-07T05:31:56Z",
"deactivated_at": "2023-11-07T05:31:56Z",
"deactivated_by": "<string>",
"deactivated_reason": "<string>",
"updated_at": "2023-11-07T05:31:56Z"
}Update webhook endpoint
Change an endpoint’s URL, events, description, auth token, payload mode, or active state.
curl --request PATCH \
--url https://api.usenexio.com/api/v1/webhooks/{endpointID} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://api.example.com/nexio/webhooks/v2",
"active": true
}
'import requests
url = "https://api.usenexio.com/api/v1/webhooks/{endpointID}"
payload = {
"url": "https://api.example.com/nexio/webhooks/v2",
"active": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({url: 'https://api.example.com/nexio/webhooks/v2', active: true})
};
fetch('https://api.usenexio.com/api/v1/webhooks/{endpointID}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "<string>",
"environment": "test",
"events": [
"run.completed"
],
"active": true,
"auth_token_configured": true,
"webhook_version": "<string>",
"payload_mode": "full",
"created_at": "2023-11-07T05:31:56Z",
"description": "<string>",
"previous_secret_expires_at": "2023-11-07T05:31:56Z",
"deactivated_at": "2023-11-07T05:31:56Z",
"deactivated_by": "<string>",
"deactivated_reason": "<string>",
"updated_at": "2023-11-07T05:31:56Z"
}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.
Path Parameters
Webhook endpoint UUID.
Body
At least one field is required.
1run.completed, run.failed, run.cancelled, run.superseded At most 256 UTF-8 bytes after trimming.
false (or null, which is read as false) deactivates the endpoint; true reactivates it.
At most 1024 UTF-8 bytes after trimming. Set to null or an empty string to clear the bearer token.
Delivery body shape. Omit to keep the current mode; an empty value is rejected.
full, thin Response
Updated endpoint.
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.
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.