Events overview

Nexio has three event mechanisms. They solve different problems, they have different guarantees, and only two of them are contracts you build against. This page tells you which one to use.

Mechanism	What it carries	Who configures it	Public contract	Guarantee
Webhooks	Terminal run results (`run.completed`, `run.failed`, `run.cancelled`) and run corrections (`run.superseded`), pushed to your HTTPS endpoint	You, with the API or the portal	Yes	Signed, at least once, unordered, retried with backoff (for about 3.3 days on `standard-v3`, the retry policy of a new endpoint)
Platform events	Facts about your organization’s data and work: a dataset refreshed, a sync finished, a check failed, documents re-indexed, a schedule fired, a deploy finished	Nexio, for your organization	The event model and the event types are documented. There is no public API to read the log	Append-only, deduplicated, drives automations
Realtime	Live progress for the portal’s screens	Nexio	No	Best effort, may change without notice

Two related capabilities sit next to these:

Inbound events let your systems append platform events to your organization’s log through POST /api/v1/events/ingest/{source_key}, authenticated per source kind: an HMAC signature for nexio and github sources, or the shared authentication code AMS360 sends for an ams360_ons source. A nexio source sends event types from your own vocabulary. This is a public route, but Nexio registers the source for you first.
Automations are rules Nexio sets up for your organization that react to platform events or a schedule with one of four fixed effects: running an engine, starting an evaluation, emitting another event, or posting to one of your webhook endpoints.

Which one to use

You want to	Use
Know when a run you submitted is finished, and get its result	Webhooks, with polling `GET /api/v1/runs/{run_id}` as the fallback and source of truth. `GET` does not return corrections; see run.superseded
Learn when a corrected result replaces one you already received	Subscribe your endpoint to `run.superseded`, and set `notify_on_supersede: true` in the engine’s configuration. What the delivery carries depends on your organization’s delivery setup; see run.superseded
Tell Nexio that something happened in your systems (a deploy, a record change) so an automation can react	Inbound events
Have Nexio run an engine or an evaluation on a schedule, or when data changes	Ask Nexio to configure an automation
Be told when your organization’s served data refreshes	Ask Nexio for an automation with the `deliver_webhook` effect, which posts the platform event to your webhook endpoint
Show live progress in your own UI	Poll the run. Realtime messages are not a contract

Sources of truth

For a run, the run itself is the truth. A webhook is a notification about that run. GET /api/v1/runs/{run_id} is the source of truth for a run; if a webhook and the run disagree, the run wins. The one exception is a correction: GET keeps returning the original output, and whether a run.superseded delivery carries the corrected output depends on your organization’s delivery setup. See Runs and run.superseded.
For platform facts, the event log is the truth. Each event records what happened, when, and what produced it. See Platform events.

Realtime

Nexio’s portal shows live progress (run stages, indexing progress, membership changes) over a private, per-organization realtime channel. Those messages are best effort: Nexio retries a failed publish a few times and then drops it, and there is no API to read past messages back. Their shapes follow the portal’s needs. They are not versioned and not documented as an API. Build on webhooks and polling instead. See How the platform fits together.

Webhooks

Webhook events

The four run events with full example bodies.

Platform events

The event model and the types Nexio records.

Inbound events

Send authenticated events from your systems.

Start here

Engines

Conversations

Connections and data

Records

Events and webhooks

Platform

Reference

Events overview

Which one to use

Sources of truth

Realtime

Webhooks

Webhook events

Platform events

Inbound events

​Which one to use

​Sources of truth

​Realtime

Webhooks

Webhook events

Platform events

Inbound events

Which one to use

Sources of truth

Realtime