> ## Documentation Index > Fetch the complete documentation index at: https://docs.usenexio.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Webhook Endpoint > Register a new webhook endpoint to receive run.completed and other event deliveries. ## OpenAPI ````yaml POST /api/v1/webhooks openapi: 3.1.0 info: title: Nexio API version: '1.0' description: | Nexio agentic infrastructure API. Configure engines for placement, entity analysis, and other patterns. Submit runs, poll for results, or subscribe to signed webhook callbacks. contact: email: support@usenexio.com url: https://docs.usenexio.com servers: - url: https://api.usenexio.com description: Production security: - BearerAuth: [] tags: - name: EngineManagement description: Create, configure, and manage inference engines. - name: Engines description: Engine-scoped endpoints for submitting runs and retrieving results. - name: Runs description: Retrieve and reconcile submitted runs. - name: Catalog description: >- Read current carriers and products extracted for the authenticated organization. - name: Environments description: Isolated tenancy scopes under your org (one live plus non-live sandboxes). - name: Webhooks description: Manage webhook endpoints for push-based delivery of terminal run events. paths: /api/v1/webhooks: post: tags: - Webhooks summary: Create Webhook Endpoint description: | Register a new webhook endpoint. Returns the endpoint metadata and a signing secret (`whsec_...`). The secret is displayed only once: store it securely. Nexio signs every delivery with HMAC-SHA256 using this secret. See [Webhooks Overview](/api-reference/webhooks/overview) for verification code samples. You can optionally provide an `auth_token` that Nexio will include as `Authorization: Bearer ` on outbound deliveries for simpler gateway-based filtering. Maximum active endpoints per environment: 10. Scoped partner keys require `webhooks:manage`. The endpoint is bound to the key's canonical named environment. The request cannot select or override that environment. operationId: createWebhook requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhookRequest' example: url: https://api.example.com/nexio/webhooks events: - run.completed - run.failed - run.superseded description: Production callback auth_token: token_live_123 responses: '201': description: Endpoint created. Secret is included only in this response. content: application/json: schema: $ref: '#/components/schemas/CreateWebhookResponse' example: id: 550e8400-e29b-41d4-a716-446655440000 url: https://api.example.com/nexio/webhooks environment: live events: - run.completed - run.failed - run.superseded description: Production callback active: true auth_token_configured: true webhook_version: '2026-03-22' secret: whsec_abc123def456 created_at: '2026-03-22T12:00:00Z' updated_at: '2026-03-22T12:00:00Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '409': description: Maximum active endpoints reached. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: webhook_limit_exceeded message: Maximum active webhook endpoints reached for this environment '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/AuthUnavailable' components: schemas: CreateWebhookRequest: type: object additionalProperties: false required: - url - events properties: url: type: string format: uri description: HTTPS endpoint URL to receive webhook deliveries. events: type: array minItems: 1 items: type: string enum: - run.completed - run.failed - run.superseded description: Event types to subscribe to. description: type: string maxLength: 256 description: Optional human-readable description. active: type: boolean default: true description: Whether the endpoint starts active. Defaults to `true`. auth_token: type: string maxLength: 1024 description: | Optional bearer token included as `Authorization: Bearer ` on outbound deliveries. payload_mode: type: string enum: - full - thin description: | 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}`. CreateWebhookResponse: allOf: - $ref: '#/components/schemas/WebhookEndpoint' - type: object required: - secret properties: secret: type: string description: | HMAC-SHA256 signing secret (`whsec_...`). Displayed only once. Store it securely. Error: type: object required: - code - message properties: code: type: string description: | Stable snake_case error identifier. Safe to match programmatically. Known codes: `invalid_request`, `invalid_input`, `unauthorized`, `auth_unavailable`, `rate_limited`, `missing_run_id`, `invalid_run_id`, `run_not_found`, `invalid_offerings`, `missing_input`, `queue_unreachable`, `engine_not_found`, `engine_slug_conflict`, `engine_archived`, `invalid_engine_type`, `validation_error`, `webhook_not_found`, `webhook_limit_exceeded`, `invalid_url`, `invalid_events`, `invalid_description`, `invalid_auth_token`, `missing_endpoint_id`, `invalid_endpoint_id`, `missing_delivery_id`, `invalid_delivery_id`, `delivery_not_found`, `delivery_not_resendable`, `insufficient_capability`, `engine_version_required`, `engine_version_exact_required`, `engine_version_not_found`, `engine_version_invalid_format`, `engine_version_draft_requires_sandbox_key`, `engine_version_none_released`, `test_scenario_sandbox_only`, `test_scenario_forbidden`, `test_scenario_exact_version_required`, `test_scenario_version_not_supported`, `invalid_test_scenario`, `request_bound_exceeded`, and `run_cap_exceeded`. message: type: string description: Human-readable error message. May change between versions. details: description: | Optional request-specific details. Request-bound failures use the `RequestBoundDetails` object. Validation failures may use an array of field issues or another documented object. WebhookEndpoint: type: object required: - id - url - environment - events - active - auth_token_configured - webhook_version - created_at properties: id: type: string format: uuid description: Endpoint identifier. url: type: string format: uri description: Delivery target URL. environment: type: string enum: - test - live description: Environment this endpoint receives events from. events: type: array items: type: string enum: - run.completed - run.failed - run.superseded description: Subscribed event types. description: type: string description: Human-readable description. active: type: boolean description: Whether the endpoint is active. auth_token_configured: type: boolean description: Whether an auth token is set (the token value is never returned). webhook_version: type: string description: Payload version string (e.g. `2026-03-22`). payload_mode: type: string enum: - full - thin description: >- Delivery body shape. `full` (default) carries the complete run; `thin` carries only run identifiers and terminal status. previous_secret_expires_at: type: string format: date-time description: Exact instant when the previous secret stops being valid. deactivated_at: type: string format: date-time description: >- Present only while the system has deactivated the endpoint after a consecutive dead-letter streak. Cleared on re-enable. deactivated_by: type: string description: >- Actor that deactivated the endpoint (`system` for the automatic dead-letter streak deactivation). Present only while deactivated. deactivated_reason: type: string description: >- Why the endpoint was deactivated, including the triggering delivery ID. Present only while deactivated. created_at: type: string format: date-time description: RFC 3339 creation timestamp. updated_at: type: string format: date-time description: RFC 3339 last-update timestamp. responses: BadRequest: description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidRequest: summary: Malformed JSON value: code: invalid_request message: Request body is not valid JSON invalidInput: summary: Input validation failed value: code: invalid_input message: Input failed validation details: - field: input.address.state message: address.state is required for placement runs. invalidOfferings: summary: Placement run missing offerings value: code: invalid_offerings message: Inline offerings failed validation details: - field: offerings message: >- Offerings are required for placement runs. Pass provider offerings in the top-level offerings array. Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unauthorized message: Missing or invalid API key RateLimited: description: Rate limit exceeded. Retry after the window resets. headers: Retry-After: description: Seconds until the rate limit window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limited message: Rate limit exceeded AuthUnavailable: description: API key authentication is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: auth_unavailable message: API key authentication is temporarily unavailable securitySchemes: BearerAuth: type: http scheme: bearer description: | Send the credential as `Authorization: Bearer `. Scoped partner credentials use the exclusive `nxsk_v1_...` namespace. Each scoped key is bound at issuance to one organization, one canonical named environment, an explicit engine set, and a least-privilege capability set. A malformed, unknown, rotated, or revoked `nxsk_` key fails closed and is never retried as a legacy key. Capabilities used by this API are `runs:write`, `runs:read`, `engines:read`, `catalog:read`, `webhooks:manage`, `runs:defensibility:read`, `runs:test`, and `converse:use`. Operation descriptions name the required capability. Grandfathered `nx_live_...` and `nx_test_...` keys retain their existing broad access during the compatibility window. ````