Reference

Realtime and events

Canonical event vocabulary, outbox-backed delivery, ordered streams, SSE, WebSocket, GraphQL subscriptions, replay, and field-names-only change events.

GraphQLGraphQL referenceCompiled SDL, query and mutation shapes, pagination, filters, subscriptions, errors, and examples.gRPCgRPC referenceProto services, metadata, streaming, status mapping, deadlines, reflection, and generated clients.WebhooksWebhooks referenceInbound and outbound delivery, signatures, retries, replay, idempotency, and receiver contracts.MCPMCP referenceJSON-RPC methods, resource metadata, token model, tools, resources, prompts, errors, and observability.ErrorsErrors referenceCanonical error envelopes, HTTP status mapping, machine-readable codes, reason codes, and correlation IDs.

Events are the canonical operational record. Realtime, webhooks, GraphQL subscriptions, automation triggers, and ordered stream consumers all consume typed event/subscription descriptors rather than inventing separate event models.

Event routes

GET /api/Event
GET /api/Event/{id}
GET /api/Event/Diagnostics

POST /api/OperationalResource/streams/{providerName}/{streamName}/append
POST /api/OperationalResource/streams/{providerName}/{streamName}/consume
POST /api/OperationalResource/streams/{streamName}/groups/{consumerGroup}/ack
POST /api/OperationalResource/streams/{providerName}/{streamName}/nack
POST /api/OperationalResource/streams/{streamName}/groups/{consumerGroup}/seek
POST /api/OperationalResource/streams/{providerName}/{streamName}/trim

Realtime subscriptions

realtime.example

curl -N "https://api.vadyl.app/v1/realtime/sse?entity=Order&filter=%7B%22status%22%3A%7B%22eq%22%3A%22paid%22%7D%7D" \
  -H "Authorization: Bearer $VADYL_TOKEN" \
  -H "X-Vadyl-Tenant: acme" \
  -H "X-Vadyl-Project: billing"

Why change events omit values

Realtime change events include entity identity and changed field names, never field values. The subscriber re-reads through the canonical read path, which re-applies row and field access policy.

Event payload shape

{
  "id": "evt_123",
  "type": "order.paid",
  "occurredAt": "2026-05-07T10:15:30Z",
  "tenantId": "ten_123",
  "projectId": "proj_456",
  "publicationVersion": 412,
  "correlationId": "01HXZ0J4YV8AJF2GFG2T1F7Y42",
  "data": {
    "orderId": "ord_123",
    "total": "29.99",
    "currency": "USD"
  }
}

Subscription filters

Filters use the typed SubscriptionFilterAst shared by realtime, webhooks, automation, GraphQL subscriptions, and event consumers. Operators include equality, set membership, prefix/suffix, numeric comparison, null checks, and bounded boolean composition.

Replay

POST /api/events/{id}/replay
{
  "target": "webhook:wh_end_123",
  "reason": "receiver outage recovery"
}

HTTP/1.1 202 Accepted
{
  "replayId": "replay_123",
  "eventId": "evt_123",
  "state": "scheduled"
}

gRPC

Webhooks