Webhook events

An endpoint receives one of four events. The webhook event types are a fixed set, defined in code, and every one is about a run. Each has the same envelope: id, type, webhook_version, created_at, and data.run. This page shows when each event fires and a full full-mode body for each. Registration, headers, signatures, and retries are on Webhooks. The schema is WebhookEvent in the OpenAPI document.

Event	Fires when	`data.run.status`	Carries `output`
`run.completed`	The run reached `completed` or `degraded`	`completed` or `degraded`	Yes
`run.failed`	The run reached `failed`	`failed`	No
`run.cancelled`	The run reached `cancelled`	`cancelled`	No
`run.superseded`	Nexio attached a corrected result to a run, and the engine’s configuration sets `notify_on_supersede: true`	The run’s status	Depends on your organization’s delivery setup; see run.superseded

Rules that hold for every event:

data.run is built from the stored run with the same status fields GET /api/v1/runs/{run_id} returns, but it is not the same response. It never carries output_phase, completed_deterministic_at, warnings, work_items, input, computed_at_head, served_head or stale; those come only from GET. output is the stored output: it is not trimmed to the operator summary as GET trims a matching run’s output, and no seat’s field policy is applied to it. Read the run with GET when you need what a person would see. Its fields are defined on Runs.
output and solutions appear only on completed and degraded runs. solutions appears only for engines that produce ranked solutions. output has the shape of the engine’s own output contract.
The event id is a UUID derived from the event type and the run ID, so a retried or resent delivery carries the same id. In one delivery setup, a run.superseded id is derived from the correction instead; see run.superseded.
In thin mode, data.run carries only run_id, status, environment, attempt, created_at, completed_at, and error. See Payload modes.

The examples use the contract fixture engine that Nexio publishes for testing (an entity_analysis engine). The run.completed, run.failed and run.superseded examples are sandbox runs with a forced test_scenario (see Sandbox fixtures), so environment is test. Your engine’s output has its own shape, and stage is a progress hint whose values differ by engine.

run.completed

Fires once, when the run reaches completed or degraded. There is no separate degraded event. A degraded run finished and returned an output that is incomplete or of reduced quality. What makes a run degraded depends on the engine type; see Runs. For example, an entity_analysis run whose enrichment source (such as FEMA flood data) timed out stays completed, with the gap recorded in the output’s diagnostics. Check data.run.status and the output’s diagnostics before you treat a result as clean.

{
  "id": "c4a1e9d2-7b3f-5e60-8a14-2d9f6b0c3e71",
  "type": "run.completed",
  "webhook_version": "2026-03-22",
  "created_at": "2026-09-23T14:05:32Z",
  "data": {
    "run": {
      "run_id": "8b3e6f1a-2c47-4d9e-a5b0-7f1c3d9e2a64",
      "engine_type": "entity_analysis",
      "engine_version": "1.0",
      "engine_config_version_hash": "f96a86a609a2b1ea",
      "status": "completed",
      "environment": "test",
      "stage": "COMPLETE",
      "output": {
        "diagnostics": [],
        "enrichment": {
          "fema_nfhl": {
            "attempted": true,
            "fetched_at": "2026-07-09T15:04:05Z",
            "kind": "fema_nfhl",
            "payload": {
              "base_flood_elevation_feet": null,
              "flood_zone": "AE",
              "flood_zone_confidence": "rooftop",
              "flood_zone_description": "High flood risk",
              "flood_zone_subtype": "",
              "matched_address": "100 Main St, Example, NC 28202",
              "matched_feature_count": 1,
              "sfha": null
            },
            "status": "succeeded"
          }
        },
        "fixture_contract": {
          "decision": "accepted"
        },
        "gaps": [],
        "profile_summary": {},
        "response_type": "GENERIC_FIXTURE_ANALYSIS",
        "summary": {
          "high_severity": 0,
          "low_severity": 0,
          "medium_severity": 0,
          "total_gaps": 0
        }
      },
      "duration_ms": 28410,
      "total_duration_ms": 29000,
      "attempt": 1,
      "trace_id": "9c900cbde9ec92b1953f4b42858a8710",
      "created_at": "2026-09-23T14:05:02Z",
      "started_at": "2026-09-23T14:05:03Z",
      "completed_at": "2026-09-23T14:05:31Z"
    }
  }
}

The same event for a degraded run differs in status and in the output the engine returned. This example is the fixture engine’s forced degraded result ("test_scenario": "degraded"). Its output carries only an enrichment timeout, which in a live entity_analysis run would leave the run completed.

{
  "id": "0e8f5b21-6c9a-5d47-b3e2-8a1f4c7d9b06",
  "type": "run.completed",
  "webhook_version": "2026-03-22",
  "created_at": "2026-09-23T14:11:09Z",
  "data": {
    "run": {
      "run_id": "3d7a9c15-e2b4-4f68-8d01-6b5e2c9f7a43",
      "engine_type": "entity_analysis",
      "engine_version": "1.0",
      "engine_config_version_hash": "f96a86a609a2b1ea",
      "status": "degraded",
      "environment": "test",
      "stage": "COMPLETE",
      "output": {
        "diagnostics": [
          {
            "code": "ENRICHMENT_DEGRADED",
            "details": {
              "error_class": "timeout",
              "upstream": "nfhl"
            },
            "message": "",
            "severity": "warn",
            "source": "fema_nfhl"
          }
        ],
        "enrichment": {
          "fema_nfhl": {
            "attempted": true,
            "diagnostics": [
              {
                "code": "ENRICHMENT_DEGRADED",
                "details": {
                  "error_class": "timeout",
                  "upstream": "nfhl"
                },
                "message": "",
                "severity": "warn",
                "source": "fema_nfhl"
              }
            ],
            "kind": "fema_nfhl",
            "status": "unavailable"
          }
        },
        "fixture_contract": {
          "decision": "review"
        },
        "gaps": [],
        "profile_summary": {},
        "response_type": "GENERIC_FIXTURE_ANALYSIS",
        "summary": {
          "high_severity": 0,
          "low_severity": 0,
          "medium_severity": 0,
          "total_gaps": 0
        }
      },
      "duration_ms": 41870,
      "total_duration_ms": 42000,
      "attempt": 1,
      "trace_id": "4be1f07a93c2d85e61a0b7c4d9e3f218",
      "created_at": "2026-09-23T14:10:26Z",
      "started_at": "2026-09-23T14:10:27Z",
      "completed_at": "2026-09-23T14:11:08Z"
    }
  }
}

Webhook deliveries never carry a warnings array. If the engine’s saved configuration turns on expose_warnings (off by default), read the run with GET /api/v1/runs/{run_id} to get it. The setting is read on each request (see Configuration).

run.failed

Fires once, when the run reaches failed. There is no output. error is a readable message and error_details is structured detail. attempt is the attempt on which the run failed; a value above 1 means Nexio retried the run before it gave up. The example is the fixture engine’s forced failed result ("test_scenario": "failed"); a live failure carries the engine’s own error and error_details.

{
  "id": "7a2d4f98-1e3b-5c06-9f7a-2b8e5d1c4a39",
  "type": "run.failed",
  "webhook_version": "2026-03-22",
  "created_at": "2026-09-23T14:20:45Z",
  "data": {
    "run": {
      "run_id": "f1c86e3b-9a27-4d5f-b04e-2c7a9e1d6b58",
      "engine_type": "entity_analysis",
      "engine_version": "1.0",
      "engine_config_version_hash": "f96a86a609a2b1ea",
      "status": "failed",
      "environment": "test",
      "stage": "FAILED",
      "duration_ms": 3120,
      "total_duration_ms": 44000,
      "attempt": 1,
      "error": "fixture provider failed",
      "error_details": {
        "code": "FIXTURE_PROVIDER_FAILURE"
      },
      "trace_id": "d2a8e4b61f7c93054e1b8a6c2d9f7e30",
      "created_at": "2026-09-23T14:20:00Z",
      "started_at": "2026-09-23T14:20:40Z",
      "completed_at": "2026-09-23T14:20:44Z"
    }
  }
}

run.cancelled

Fires once, when the run reaches cancelled. A run is cancelled when someone asks for it with POST /api/v1/runs/{run_id}/cancel. A queued run is cancelled at once; a running run stops at its next safe point. There is no output. See Runs for cancellation.

{
  "id": "2b9e6c14-8d3f-5a71-a6c0-4e2f8b7d1c95",
  "type": "run.cancelled",
  "webhook_version": "2026-03-22",
  "created_at": "2026-09-23T14:31:18Z",
  "data": {
    "run": {
      "run_id": "6e4b2a97-c1d8-4f3e-9b75-8a2c6d0e4f11",
      "engine_type": "entity_analysis",
      "engine_version": "1.0",
      "engine_config_version_hash": "f96a86a609a2b1ea",
      "status": "cancelled",
      "environment": "live",
      "stage": "cancelled",
      "total_duration_ms": 16000,
      "attempt": 1,
      "trace_id": "71c3e9a0b5d2f84e6a1c7b3d9e0f2a58",
      "created_at": "2026-09-23T14:31:01Z",
      "started_at": "2026-09-23T14:31:02Z",
      "completed_at": "2026-09-23T14:31:17Z"
    }
  }
}

run.superseded

Fires when Nexio attaches a corrected result to a run. Nexio keeps the original result. Corrections are made by Nexio; there is no public route to create one. See Defensibility. Two conditions must both hold:

The engine’s configuration sets notify_on_supersede: true. It is false by default. Which configuration Nexio reads depends on your organization’s delivery setup (see the table below and Configuration).
The endpoint lists run.superseded in events.

Nexio sets your organization’s delivery setup. A new organization starts in the per-run setup. Ask Nexio which one yours uses.

	Per-correction setup	Per-run setup
Configuration Nexio reads	The configuration the run executed, so `notify_on_supersede` must be in the version the run used	The engine’s saved configuration when the correction is recorded
Event `id`	Derived from the correction, so each correction of a run is a new event	Derived from the event type and the run ID, so a later correction of the same run sends no new delivery to an endpoint that already received one
`data.run` in a `full` body	The corrected output, when the run is `completed` or `degraded`, and no `solutions`	The run’s stored (original) output and its `solutions`, as on `run.completed`

In both setups GET /api/v1/runs/{run_id} keeps returning the original output, and a thin endpoint receives no output. In the per-correction setup the corrected output reaches you only in a full run.superseded delivery. In the per-run setup the delivery tells you that a correction exists but does not carry it. The example is a full body in the per-correction setup, correcting the run.completed example above.

{
  "id": "9f3c7e20-4a6b-5d18-8e92-1b7d3f5a0c64",
  "type": "run.superseded",
  "webhook_version": "2026-03-22",
  "created_at": "2026-09-24T09:12:40Z",
  "data": {
    "run": {
      "run_id": "8b3e6f1a-2c47-4d9e-a5b0-7f1c3d9e2a64",
      "engine_type": "entity_analysis",
      "engine_version": "1.0",
      "engine_config_version_hash": "f96a86a609a2b1ea",
      "status": "completed",
      "environment": "test",
      "stage": "COMPLETE",
      "output": {
        "diagnostics": [],
        "enrichment": {
          "fema_nfhl": {
            "attempted": true,
            "fetched_at": "2026-07-09T15:04:05Z",
            "kind": "fema_nfhl",
            "payload": {
              "base_flood_elevation_feet": null,
              "flood_zone": "X",
              "flood_zone_confidence": "rooftop",
              "flood_zone_description": "Minimal flood risk",
              "flood_zone_subtype": "",
              "matched_address": "100 Main St, Example, NC 28202",
              "matched_feature_count": 1,
              "sfha": null
            },
            "status": "succeeded"
          }
        },
        "fixture_contract": {
          "decision": "accepted"
        },
        "gaps": [],
        "profile_summary": {},
        "response_type": "GENERIC_FIXTURE_ANALYSIS",
        "summary": {
          "high_severity": 0,
          "low_severity": 0,
          "medium_severity": 0,
          "total_gaps": 0
        }
      },
      "duration_ms": 28410,
      "total_duration_ms": 29000,
      "attempt": 1,
      "trace_id": "9c900cbde9ec92b1953f4b42858a8710",
      "created_at": "2026-09-23T14:05:02Z",
      "started_at": "2026-09-23T14:05:03Z",
      "completed_at": "2026-09-23T14:05:31Z"
    }
  }
}

Because deliveries are unordered, a run.superseded delivery can reach you before the run.completed for the same run. Key your stored result on run_id. In the per-correction setup, let the corrected output win over the original, whatever order they arrive in.

Events that do not exist

There is no run.degraded event. Degraded runs arrive as run.completed.
There are no events for runs that are queued or processing. Poll the run for progress.
Platform event types such as dataset.refreshed are not webhook events and cannot be listed in an endpoint’s events. Nexio can deliver them to your endpoint through an automation; see Platform event deliveries.

Webhooks

Runs

Every field of the run object.

Start here

Engines

Conversations

Connections and data

Records

Events and webhooks

Platform

Reference

Webhook events

run.completed

run.failed

run.cancelled

run.superseded

Events that do not exist

Webhooks

Runs

​run.completed

​run.failed

​run.cancelled

​run.superseded

​Events that do not exist

Webhooks

Runs

run.completed

run.failed

run.cancelled

run.superseded

Events that do not exist