Skip to content

events.md

Latest commit

 

History

History
105 lines (80 loc) · 4.57 KB

events.md

File metadata and controls

105 lines (80 loc) · 4.57 KB
Raw

Events

Snaapi automatically emits events whenever records are created, updated, or deleted. Events follow a Hasura-style data structure that captures the full before/after state of each change, along with session and trace context for auditing and distributed tracing.

Event Types

Events follow the resourceName.action naming convention:

Event Type Description
resource.created A new record was created
resource.updated An existing record was modified
resource.deleted A record was deleted (soft or hard)

For example, a resource named posts would emit posts.created, posts.updated, and posts.deleted events.

Event Data Structure

Each event record contains the following fields:

Field Type Description
id string Internal record ID
eventId string Unique event ID (UUID)
eventType string Event type (e.g., posts.created)
resourceName string Name of the resource (e.g., posts)
resourceId string ID of the affected resource record
createdAt string ISO 8601 timestamp of when the event occurred
dispatchedAt string or null Timestamp when dispatched to job executions
data object (see below) Hasura-style old/new/changes object
sessionVariables object or null Request context (user, role, IP)
traceContext object or null Distributed tracing identifiers

Hasura-Style Data Object

The data field captures the full state change:

{
  "old": null,
  "new": { "id": "abc-123", "title": "Hello World" },
  "changes": {
    "added": ["id", "title", "created_at"],
    "updated": [],
    "removed": []
  }
}
Field Type Description
old object or null Previous state of the record (null for created)
new object or null Current state of the record (null for deleted)
changes object Arrays describing which fields changed

Changes Object

Field Type Description
added array of strings Fields that were added
updated array of strings Fields that were modified
removed array of strings Fields that were removed

For created events, all fields appear in added. For deleted events, all fields appear in removed. For updated events, only modified fields appear in updated.

Session Variables

Session variables capture the request context at the time the event was emitted:

Field Type Description
userId string ID of the authenticated user
role string Role of the authenticated user
ip string Client IP address
userAgent string Client User-Agent header

Additional custom properties may also be present.

Trace Context

Trace context enables correlation with distributed tracing systems like OpenTelemetry:

Field Type Description
traceId string OpenTelemetry trace ID
spanId string OpenTelemetry span ID
parentSpanId string Parent span ID (if applicable)
requestId string Unique ID for the originating HTTP request
correlationId string Correlation ID for grouping related events

Additional custom properties may also be present.

What Happens with Events

Events are delivered to webhook endpoints you configure, streamed to SSE connections for realtime updates, and recorded for audit. See Webhooks, Realtime, and Jobs for details.