Skip to content
Sparrow

EventService

EventService manages event type definitions and event pushing. Event types must be registered before they can be pushed. Each event type has a unique name (scoped to the default tenant) and an optional JSON schema for payload validation.

RegisterEvent

POST /webhook.EventService/RegisterEvent

RegisterEvent creates a new event type definition. If a JSON schema is provided, all future PushEvent payloads for this event are validated against it. The event name is the primary identifier (not a UUID). Errors: ALREADY_EXISTS if an event with the same name already exists.

Request

namestring

Unique event name (e.g., "order.created", "payment.completed"). Required. Convention: use dot-separated lowercase names.

descriptionstring

Human-readable description of what this event represents. Optional.

schemaStruct (JSON)

JSON Schema for validating PushEvent payloads. Optional. When set, all future PushEvent calls for this event type must conform to this schema. Passed as a google.protobuf.Struct (JSON object).

metadatamap<string, string>

Arbitrary key-value metadata attached to the event type definition. Optional.

activebool

Whether the event type is active. Default: true. Inactive event types cannot receive new PushEvent calls.

Response

event_idstring

The event type name.

created_atTimestamp

When the event type was created.

Request
curl -X POST http://localhost:8080/webhook.EventService/RegisterEvent \
  -H "Content-Type: application/json" \
  -d '{
  "name": "order.created",
  "description": "Fired when a new order is placed",
  "schema": {
    "properties": {
      "amount": {
        "type": "number"
      },
      "order_id": {
        "type": "string"
      }
    },
    "required": [
      "order_id",
      "amount"
    ],
    "type": "object"
  },
  "active": true
}'

ListEvents

POST /webhook.EventService/ListEvents

ListEvents returns all registered event types, optionally filtered to active-only. Results are paginated.

Request

active_onlybool

When true, only return active event types. Default: false (return all).

paginationPaginationRequest

Pagination parameters. Default: limit=50, offset=0.

Response

eventsRegisteredEvent[]

Event type definitions matching the filter criteria.

paginationPaginationResponse

Pagination metadata.

Request
curl -X POST http://localhost:8080/webhook.EventService/ListEvents \
  -H "Content-Type: application/json" \
  -d '{
  "active_only": true
}'

UpdateEvent

POST /webhook.EventService/UpdateEvent

UpdateEvent modifies an existing event type's description, schema, metadata, or active flag. Updating the schema does not retroactively validate previously pushed events. Errors: NOT_FOUND if the event name does not exist.

Request

namestring

Event name to update. Required. This is the lookup key (not a UUID).

descriptionstring

Updated description. Omit to leave unchanged.

schemaStruct (JSON)

Updated JSON Schema for payload validation. Omit to leave unchanged. Note: changing the schema does not retroactively validate previously pushed events.

metadatamap<string, string>

Updated metadata. Omit to leave unchanged.

activebool

Updated active flag. Omit to leave unchanged.

Request
curl -X POST http://localhost:8080/webhook.EventService/UpdateEvent \
  -H "Content-Type: application/json" \
  -d '{
  "name": "order.created",
  "description": "Updated: Fired when a new order is placed"
}'

DeleteEvent

POST /webhook.EventService/DeleteEvent

DeleteEvent permanently removes an event type definition. Existing subscriptions referencing this event name are not automatically deleted. Errors: NOT_FOUND if the event name does not exist.

Request

namestring

Event name to delete. Required.

Request
curl -X POST http://localhost:8080/webhook.EventService/DeleteEvent \
  -H "Content-Type: application/json" \
  -d '{
  "name": "order.created"
}'

GetEvent

POST /webhook.EventService/GetEvent

GetEvent returns a single event type by name, including its schema and auto-generated sample payload. Errors: NOT_FOUND if the event name does not exist.

Request

namestring

Event name to look up. Required.

Response

eventRegisteredEvent

The event type definition, including schema and sample_payload.

Request
curl -X POST http://localhost:8080/webhook.EventService/GetEvent \
  -H "Content-Type: application/json" \
  -d '{
  "name": "order.created"
}'

PushEvent

POST /webhook.EventService/PushEvent

PushEvent emits an event instance. This is the primary ingestion endpoint. On success, the event is persisted and a background job is enqueued to fan out deliveries to all matching subscriptions (by namespace + event_name + label_filters). The response returns immediately with the event_id; delivery happens asynchronously. If the event type has a JSON schema, the payload is validated before acceptance. Errors: INVALID_ARGUMENT if the payload fails schema validation. Errors: NOT_FOUND if the event name is not registered.

Request

namespacestring

Namespace to push the event into. Required. Only subscriptions in this namespace are matched.

eventstring

Event type name (must match a registered event type). Required. Subscriptions with matching event_name in this namespace will receive deliveries.

payloadStruct (JSON)

Event payload as a JSON object. Required. If the event type has a schema, this payload is validated against it before acceptance. This payload (or its template-transformed version) becomes the HTTP request body sent to each matching webhook.

ttl_secondsint64

Time-to-live in seconds for delivery retries. Optional. When set, deliveries that haven't succeeded within this window transition to EXPIRED. Default: 0 (no expiration -- retries continue until max_retries is exhausted).

metadatamap<string, string>

Arbitrary key-value metadata attached to this event instance. Optional. Metadata is stored with the event record and available in event reports, but is NOT included in the delivery payload sent to webhooks.

idstring

Client-provided event ID for idempotency. Optional. If provided and an event with this ID already exists, the existing event_id is returned without creating a duplicate.

labelsmap<string, string>

Labels for label-based subscription matching. Optional. When set, only subscriptions whose label_filters are a subset of these labels will receive deliveries. Labels use AND logic: all filter keys must match. Subscriptions with no label_filters match all events regardless of labels.

Response

event_idstring

Server-generated UUID for the event instance. Use this ID to query delivery status via DeliveryService.ListDeliveries.

warningsstring[]

Schema validation warnings. Populated when the event payload does not match the registered JSON schema. The event is still accepted and stored, but schema_valid is set to false on the event record. Each string describes a specific validation failure (e.g., "field 'amount': expected number, got string"). Empty when the payload passes validation or no schema is registered.

duplicatebool

True when the request was deduplicated by idempotency key. The returned event_id belongs to the previously created event. No new event record or deliveries are created.

Request
curl -X POST http://localhost:8080/webhook.EventService/PushEvent \
  -H "Content-Type: application/json" \
  -d '{
  "namespace": "production",
  "event": "order.created",
  "payload": {
    "amount": 99.99,
    "currency": "USD",
    "order_id": "ord-123"
  },
  "labels": {
    "priority": "high",
    "region": "us-east"
  }
}'
Response
{
  "event_id": "e-550e8400-e29b-41d4-a716-446655440000"
}

ListEventReports

POST /webhook.EventService/ListEventReports

ListEventReports returns pushed event instances (not type definitions) for a namespace, ordered by created_at descending. Each report includes delivery stats (webhook_count, successful/failed/pending counts). Paginated, max 1000 per page.

Request

namespacestring

Namespace to list events from. Required.

event_namestring

Filter to events of this type name. Optional.

paginationPaginationRequest

Pagination parameters. Default: limit=50, offset=0. Max limit: 1000.

schema_validbool

Filter by schema validation status. When set, only events matching the specified schema_valid value are returned.

labelsmap<string, string>

Filter by labels using JSONB containment. Only events whose labels contain all specified key-value pairs are returned.

created_afterTimestamp

Filter to events created at or after this timestamp.

created_beforeTimestamp

Filter to events created at or before this timestamp.

prepare_repushbool

When true, snapshot all matching event IDs (up to 10,000) into a batch job and return a repush_id in the response. Pass that ID to RePushEvents to re-push the exact set of events that matched this query.

Response

eventsEventReport[]

Event instances ordered by created_at descending (newest first).

paginationPaginationResponse

Pagination metadata.

repush_idstring

Batch ID for deterministic re-push. Only populated when prepare_repush=true was set in the request. Pass to RePushEvents.

Request
curl -X POST http://localhost:8080/webhook.EventService/ListEventReports \
  -H "Content-Type: application/json" \
  -d '{
  "namespace": "production",
  "event_name": "order.created",
  "pagination": {
    "limit": 25
  },
  "labels": {
    "region": "us-east"
  }
}'

GetEventRecord

POST /webhook.EventService/GetEventRecord

GetEventRecord retrieves a single pushed event instance by its UUID. Returns the event record with its payload, metadata, labels, and aggregated delivery statistics (webhook_count, successful/failed/pending counts). This is different from GetEvent which returns an event type definition by name. Errors: NOT_FOUND if the event_id does not exist. Errors: INVALID_ARGUMENT if the event_id is not a valid UUID.

Request

event_idstring

UUID of the event instance. Required.

Response

eventEventReport

The event instance with aggregated delivery statistics.

labelsmap<string, string>

Labels attached when the event was pushed.

expires_atTimestamp

When the event expires (based on TTL). Zero value if no TTL was set.

Request
curl -X POST http://localhost:8080/webhook.EventService/GetEventRecord \
  -H "Content-Type: application/json" \
  -d '{
  "event_id": "e-550e8400-e29b-41d4-a716-446655440000"
}'

RePushEvent

POST /webhook.EventService/RePushEvent

RePushEvent replays a single previously pushed event as if it were pushed fresh. Loads the original event record and re-pushes through the standard PushEvent pipeline. Errors: NOT_FOUND if the event_id does not exist. Errors: INVALID_ARGUMENT if the event_id is not a valid UUID.

Request

event_idstring

UUID of the original event to replay. Required. The event must exist in the event_records table.

Response

event_idstring

Server-generated UUID for the new event instance. This is a brand-new event; the original event is not modified.

warningsstring[]

Schema validation warnings for the re-pushed payload. The original payload is validated against the CURRENT event type schema. Empty when the payload passes validation or no schema is registered.

Request
curl -X POST http://localhost:8080/webhook.EventService/RePushEvent \
  -H "Content-Type: application/json" \
  -d '{
  "event_id": "e-550e8400-e29b-41d4-a716-446655440000"
}'
Response
{
  "event_id": "e-660e8400-e29b-41d4-a716-446655440001"
}

RePushEvents

POST /webhook.EventService/RePushEvents

RePushEvents executes a deterministic batch re-push of events whose IDs were previously snapshotted via ListEventReports with prepare_repush=true. Each event is re-pushed as if it were pushed fresh: new event_id, current schema validation. The batch is processed asynchronously via a River job; poll GetRepushStatus for progress. Errors: NOT_FOUND if the repush_id does not exist or has expired. Errors: FAILED_PRECONDITION if the batch is not in 'pending' status.

Request

repush_idstringrequired

Batch ID returned by ListEventReports when prepare_repush=true.

Response

repush_idstring

Batch ID for polling status.

totalint32

Total number of events that will be re-pushed.

statusstring

Current status (will be "processing" on success).

Request
curl -X POST http://localhost:8080/webhook.EventService/RePushEvents \
  -H "Content-Type: application/json" \
  -d '{}'

GetRepushStatus

POST /webhook.EventService/GetRepushStatus

GetRepushStatus returns the current progress of a batch re-push operation. Errors: NOT_FOUND if the repush_id does not exist or has expired.

Request

repush_idstringrequired

Batch ID returned by RePushEvents or ListEventReports.

Response

batch.statusstring

Current status of the batch job.

batch.totalint32

Total number of items in the batch.

batch.processedint32

Number of items successfully processed so far.

batch.failedint32

Number of items that failed processing.

batch.created_atTimestamp

When the batch job was created.

batch.expires_atTimestamp

When the batch job expires (created_at + ttl_seconds).

Request
curl -X POST http://localhost:8080/webhook.EventService/GetRepushStatus \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "batch": {
    "status": "processing"
  }
}

CancelRepush

POST /webhook.EventService/CancelRepush

CancelRepush aborts a batch re-push that is pending or in progress. Items already processed are not rolled back. Errors: NOT_FOUND if the repush_id does not exist. Errors: FAILED_PRECONDITION if the batch is already completed or cancelled.

Request

repush_idstringrequired

Batch ID to cancel.

Response

statusstring

Current status after cancellation (will be "cancelled").

Request
curl -X POST http://localhost:8080/webhook.EventService/CancelRepush \
  -H "Content-Type: application/json" \
  -d '{}'
v1.3.5 · Built on June 22, 2026