Skip to main content
Base path: https://api.usenexio.com/api/v1/webhooks
Use webhooks when you want Nexio to push terminal run updates to your backend instead of waiting for your next poll. Polling GET /api/v1/jobs/{run_id} is still the canonical reconciliation read.

​
Supported Events

  • evaluation.completed
  • evaluation.failed

​
Manage Endpoints

​
Create endpoint

POST /api/v1/webhooks 
{
  "url": "https://api.example.com/nexio/webhooks",
  "events": ["evaluation.completed", "evaluation.failed"],
  "description": "Production callback"
}
Response: 
{
  "id": "uuid",
  "url": "https://api.example.com/nexio/webhooks",
  "environment": "live",
  "events": ["evaluation.completed", "evaluation.failed"],
  "description": "Production callback",
  "active": true,
  "webhook_version": "2026-03-22",
  "secret": "whsec_...",
  "created_at": "2026-03-22T12:00:00Z"
}

​
List endpoints

GET /api/v1/webhooks Returns endpoint metadata for the authenticated org_id + environment. Secrets are never returned on list responses.

​
Update endpoint

PATCH /api/v1/webhooks/{endpoint_id} Allowed fields:
  • url
  • events
  • description
  • active
Setting active to false cancels pending deliveries for that endpoint. Updating url affects only future deliveries because each delivery snapshots its own target_url.

​
Rotate secret

POST /api/v1/webhooks/{endpoint_id}/rotate-secret Returns a new secret once and keeps the previous secret valid for 24 hours so your consumer can cut over safely.

​
Delete endpoint

DELETE /api/v1/webhooks/{endpoint_id} Deactivates the endpoint and cancels its pending deliveries. Historical delivery rows are retained for audit and troubleshooting.

​
Delivery Contract

Delivery semantics:
  • at least once
  • ordering not guaranteed
  • same X-Nexio-Delivery value across retries for the same endpoint delivery
  • immutable JSON payload snapshot per delivery
Example completed event: 
{
  "id": "evt_123",
  "type": "evaluation.completed",
  "webhook_version": "2026-03-22",
  "created_at": "2026-03-22T12:00:00Z",
  "data": {
    "run": {
      "run_id": "run_123",
      "status": "completed",
      "environment": "live",
      "output": {
        "solutions_count": 2,
        "top_label": "recommended"
      },
      "solutions": []
    }
  }
}

​
Headers

HeaderValue
Content-Typeapplication/json
User-AgentNexio-Webhooks/1.0
X-Nexio-Eventevaluation.completed or evaluation.failed
X-Nexio-DeliveryStable delivery UUID
X-Nexio-TimestampUnix timestamp used in signing
X-Nexio-Webhook-VersionCurrent payload version, for example 2026-03-22
X-Nexio-Signaturet=<unix>,v1=<hex> or multiple v1= values during secret overlap

​
Verification

Required consumer behavior:
  1. Capture the raw request body.
  2. Build the signed payload as <timestamp>.<raw_body>.
  3. Compute HMAC-SHA256 with your webhook secret.
  4. Compare against every v1= signature in X-Nexio-Signature using constant-time comparison.
  5. Reject timestamps older than 5 minutes.
  6. Deduplicate on X-Nexio-Delivery.
Return 2xx quickly and process downstream work asynchronously. If you miss a delivery, receive events out of order, or want the latest canonical read, call GET /api/v1/jobs/{run_id}.