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

created_atTimestamp

Timestamp 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
}'
Response
{
  "created_at": "2025-01-15T10:30:00Z"
}

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.

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.

Response

eventsEventReport[]

Event instances ordered by created_at descending (newest first).

paginationPaginationResponse

Pagination metadata.

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
  }
}'
v1.2.1 · Built on April 10, 2026