Platform — Infrastructure

Event Systems

Ventryx is built around events. Everything that happens on the platform — a workflow completing, an approval being granted, a rate limit being exceeded — produces a structured event that you can react to in real time.

Event model

Every event has a consistent structure regardless of type:

Event object

{
  "id": "evt_01HXYZ",
  "type": "workflow.completed",
  "created_at": "2026-04-03T09:15:00.000Z",
  "data": {
    "workflow_id": "wf_01HXYZ",
    "run_id": "run_01HABC",
    "status": "success",
    "duration_ms": 412
  }
}

Event types

Event type	Triggered when
`workflow.started`	A workflow run begins
`workflow.completed`	A workflow run finishes (success or failure)
`workflow.failed`	A workflow run encounters an unrecoverable error
`approval.requested`	A step requires human approval
`approval.completed`	An approver acts on a request
`api_key.created`	A new API key is issued
`api_key.revoked`	An API key is revoked
`rate_limit.exceeded`	A key exceeds its rate limit threshold

Emitting custom events

You can emit your own domain events into the Ventryx event bus to trigger workflows or push to webhooks:

curl

curl -X POST https://api.ventryx.io/v1/events \
  -H "Authorization: Bearer $VENTRYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order.placed",
    "data": { "order_id": "ord_999", "amount": 249.00 }
  }'

Event delivery guarantees

The Ventryx event system is designed for at-least-once delivery. Events are durably persisted before acknowledgment, and any downstream webhook delivery is retried up to 5 times with exponential backoff on failure. Design your event consumers to be idempotent using the event.id field as a deduplication key.

Querying events

Past events can be retrieved via the API with filtering by type, time range, or related resource:

GET /v1/events?type=workflow.completed&from=2026-04-01&to=2026-04-03