Skip to content
Sparrow

SubscriptionService

SubscriptionService manages the mapping between webhooks and event types. A subscription links one webhook to one event name within a namespace. When an event is pushed, all subscriptions matching (namespace, event_name, label_filters) generate a delivery. Subscriptions can optionally transform the payload using Go templates.

CreateSubscription

POST /webhook.SubscriptionService/CreateSubscription

CreateSubscription links a webhook to an event name in a namespace. Optionally configure per-subscription headers, HTTP method override, timeout override, payload transformation (Go template), and label filters for selective matching. Errors: ALREADY_EXISTS if the webhook is already subscribed to this event in this namespace. Errors: NOT_FOUND if the webhook_id does not exist.

Request

webhook_idstring

UUID of the webhook to subscribe. Required. The webhook must exist in the specified namespace.

event_namestring

Event type name to subscribe to. Required.

namespacestring

Namespace for the subscription. Required. Must match the webhook's namespace.

headersmap<string, string>

Per-subscription HTTP headers. Optional. Merged with (and overrides) webhook-level headers on delivery.

methodstring

HTTP method override. Optional. Default: "POST".

timeoutint32

Timeout override in seconds. Optional. Default: use webhook's timeout.

transform_enabledbool

Enable Go template payload transformation. Default: false.

transform_templatestring

Go template for payload transformation. Only used when transform_enabled is true. Use TestSubscriptionTemplate to validate before saving.

label_filtersmap<string, string>

Label filters for selective event matching. Optional. Only events with labels matching all key-value pairs will trigger this subscription.

Response

subscription_idstring

Server-generated UUID of the new subscription.

created_atTimestamp

When the subscription was created.

Request
curl -X POST http://localhost:8080/webhook.SubscriptionService/CreateSubscription \
  -H "Content-Type: application/json" \
  -d '{
  "webhook_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_name": "order.created",
  "namespace": "production",
  "label_filters": {
    "region": "us-east"
  }
}'
Response
{
  "subscription_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "created_at": "2025-01-15T10:30:00Z"
}

GetSubscription

POST /webhook.SubscriptionService/GetSubscription

GetSubscription returns a single subscription by ID. Errors: NOT_FOUND if the subscription_id does not exist in the given namespace.

Request

subscription_idstring

UUID of the subscription to retrieve. Required.

namespacestring

Namespace the subscription belongs to. Required.

Response

subscriptionEventSubscription

Full subscription details.

Request
curl -X POST http://localhost:8080/webhook.SubscriptionService/GetSubscription \
  -H "Content-Type: application/json" \
  -d '{
  "subscription_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "namespace": "production"
}'

ListSubscriptions

POST /webhook.SubscriptionService/ListSubscriptions

ListSubscriptions returns subscriptions in a namespace, optionally filtered by webhook_id or event_name. Results are paginated.

Request

webhook_idstring

Filter by webhook UUID. Optional.

event_namestring

Filter by event type name. Optional.

namespacestring

Namespace to list subscriptions from. Required.

paginationPaginationRequest

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

Response

subscriptionsEventSubscription[]

Subscriptions matching the filter criteria.

paginationPaginationResponse

Pagination metadata.

Request
curl -X POST http://localhost:8080/webhook.SubscriptionService/ListSubscriptions \
  -H "Content-Type: application/json" \
  -d '{
  "webhook_id": "550e8400-e29b-41d4-a716-446655440000",
  "namespace": "production"
}'

UpdateSubscription

POST /webhook.SubscriptionService/UpdateSubscription

UpdateSubscription modifies a subscription's headers, method, timeout, transform settings, or label filters. Only non-zero fields are applied. Errors: NOT_FOUND if the subscription does not exist.

Request

subscription_idstring

UUID of the subscription to update. Required.

namespacestring

Namespace the subscription belongs to. Required.

headersmap<string, string>

Updated per-subscription headers. Replaces existing headers when set.

methodstring

Updated HTTP method override.

timeoutint32

Updated timeout override in seconds.

transform_enabledbool

Updated transform enabled flag.

transform_templatestring

Updated Go template. Use TestSubscriptionTemplate to validate before saving.

label_filtersmap<string, string>

Updated label filters. Replaces existing filters when set.

Request
curl -X POST http://localhost:8080/webhook.SubscriptionService/UpdateSubscription \
  -H "Content-Type: application/json" \
  -d '{
  "subscription_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "namespace": "production",
  "transform_enabled": true
}'

DeleteSubscription

POST /webhook.SubscriptionService/DeleteSubscription

DeleteSubscription permanently removes a subscription. Existing in-flight deliveries for this subscription are not cancelled. Errors: NOT_FOUND if the subscription does not exist.

Request

subscription_idstring

UUID of the subscription to delete. Required.

namespacestring

Namespace the subscription belongs to. Required.

Request
curl -X POST http://localhost:8080/webhook.SubscriptionService/DeleteSubscription \
  -H "Content-Type: application/json" \
  -d '{
  "subscription_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "namespace": "production"
}'

TestSubscriptionTemplate

POST /webhook.SubscriptionService/TestSubscriptionTemplate

TestSubscriptionTemplate renders a Go template against the sample payload of the given event type. Returns the transformed output string. Use this to validate templates before saving them on a subscription. Errors: INVALID_ARGUMENT if the template fails to parse or execute. Errors: NOT_FOUND if the event_name does not exist.

Request

event_namestring

Event name to get the sample payload from. Required. The event type must have a schema defined for a sample payload to be generated.

transform_templatestring

Go template string to test. Required. The template is executed with the event's sample_payload as its data context.

namespacestring

Namespace. Required.

Response

transformed_payloadstring

The template output after rendering against the sample payload. This is exactly what would be sent as the delivery request body if this template were applied to a subscription.

Request
curl -X POST http://localhost:8080/webhook.SubscriptionService/TestSubscriptionTemplate \
  -H "Content-Type: application/json" \
  -d '{
  "event_name": "order.created",
  "transform_template": "{\"id\": \"{{ .payload.order_id }}\", \"total\": \"{{ .payload.amount }}\"}",
  "namespace": "production"
}'
Response
{
  "transformed_payload": "{\"id\": \"ord-123\", \"total\": \"99.99\"}"
}
v1.2.1 · Built on April 10, 2026