Skip to content
Sparrow

WebhookService

WebhookService manages webhook registration, configuration, and lifecycle. All RPCs require a namespace. Webhooks are scoped to a single namespace.

RegisterWebhook

POST /webhook.WebhookService/RegisterWebhook

RegisterWebhook creates a new webhook registration. Accepts a target URL, a list of event names, and optional HTTP configuration. Subscriptions are created automatically for each event in the events list. Returns the generated webhook_id and created_at timestamp. Errors: ALREADY_EXISTS if the URL is already registered in the same namespace.

Request

namespacestring

Namespace to register the webhook in. Required. The namespace must already exist (created via the NamespaceService).

eventsstring[]

Event names this webhook should receive. At least one is required. A subscription is automatically created for each event name listed here.

urlstring

Target URL that will receive HTTP POST requests for each delivery. Must be a valid HTTP or HTTPS URL. Required.

headersmap<string, string>

Custom HTTP headers included in every delivery request to this webhook. These are visible in API responses. For sensitive values (API keys, tokens), use secret_headers instead.

timeoutint32

Deprecated: use http_config.request_timeout_seconds instead.

activebool

Whether the webhook starts in active state. Default: true. Inactive webhooks are skipped during event fan-out.

descriptionstring

Human-readable description of the webhook's purpose. Optional.

http_configWebhookHTTPConfig

HTTP delivery configuration (retries, timeouts, TLS, HMAC, etc.). Optional -- all fields have sensible defaults if omitted.

secret_headersmap<string, string>

Sensitive HTTP headers stored encrypted at rest (e.g., Authorization, API keys). Values are masked as "******" in all API responses -- only keys are visible. Included in delivery requests alongside regular headers.

Response

webhook_idstring

Server-generated UUID for the new webhook. Use this ID for all subsequent operations (update, pause, resume, unregister).

created_atTimestamp

Timestamp when the webhook was created.

Request
curl -X POST http://localhost:8080/webhook.WebhookService/RegisterWebhook \
  -H "Content-Type: application/json" \
  -d '{
  "namespace": "production",
  "events": [
    "order.created",
    "order.updated"
  ],
  "url": "https://example.com/hooks",
  "headers": {
    "X-Source": "sparrow"
  },
  "active": true,
  "description": "Order notifications",
  "http_config": {
    "max_retries": 5,
    "webhook_secret": "whsec_your_secret_key"
  }
}'
Response
{
  "webhook_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-01-15T10:30:00Z"
}

UnregisterWebhook

POST /webhook.WebhookService/UnregisterWebhook

UnregisterWebhook permanently deletes a webhook and all its subscriptions. Associated delivery records are also cascade-deleted. Errors: NOT_FOUND if the webhook_id does not exist in the given namespace.

Request

webhook_idstring

UUID of the webhook to delete. Required.

namespacestring

Namespace the webhook belongs to. Required.

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

ListWebhooks

POST /webhook.WebhookService/ListWebhooks

ListWebhooks returns webhooks for a namespace with optional filters. Supports filtering by event name, active status, or specific webhook_id. Results are paginated (default limit: 50). Each webhook includes its current health status.

Request

namespacestring

Namespace to list webhooks from. Required.

eventstring

Filter to only webhooks subscribed to this event name. Optional.

active_onlybool

When true, only return active (non-paused) webhooks. Default: false (return all).

paginationPaginationRequest

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

webhook_idstring

Filter to a specific webhook by ID. Optional. When set, returns at most one result.

Response

webhooksRegisteredWebhook[]

Webhooks matching the filter criteria.

paginationPaginationResponse

Pagination metadata (total_count, limit, offset).

Request
curl -X POST http://localhost:8080/webhook.WebhookService/ListWebhooks \
  -H "Content-Type: application/json" \
  -d '{
  "namespace": "production",
  "active_only": true,
  "pagination": {
    "limit": 20
  }
}'

UpdateWebhookConfig

POST /webhook.WebhookService/UpdateWebhookConfig

UpdateWebhookConfig patches one or more fields on an existing webhook. Only non-zero fields in WebhookUpdateFields are applied. Updating events replaces the full subscription set: removed events have their subscriptions deleted, new events get subscriptions created. Errors: NOT_FOUND if the webhook does not exist.

Request

webhook_idstring

UUID of the webhook to update. Required.

namespacestring

Namespace the webhook belongs to. Required.

updates.eventsstring[]

Replace the full list of subscribed events. Omit to leave unchanged. Passing a non-empty list replaces all existing subscriptions.

updates.urlstring

New target URL. Omit to leave unchanged.

updates.headersmap<string, string>

Replace all custom headers. Omit to leave unchanged. Pass an empty map to clear all headers.

updates.timeoutint32

Deprecated: use http_config.request_timeout_seconds.

updates.activebool

Set active/inactive status. Note: prefer PauseWebhook/ResumeWebhook RPCs for explicit lifecycle control with reason tracking.

updates.descriptionstring

Updated human-readable description. Omit to leave unchanged.

updates.http_configWebhookHTTPConfig

Updated HTTP delivery configuration. Omit to leave unchanged. When set, the entire http_config is replaced (not merged field-by-field).

updates.secret_headersmap<string, string>

Replace all secret headers. Omit to leave unchanged. Pass an empty map to clear all secret headers.

Request
curl -X POST http://localhost:8080/webhook.WebhookService/UpdateWebhookConfig \
  -H "Content-Type: application/json" \
  -d '{
  "webhook_id": "550e8400-e29b-41d4-a716-446655440000",
  "namespace": "production",
  "updates": {
    "description": "Updated order webhook",
    "http_config": {
      "max_retries": 5,
      "request_timeout_seconds": 60
    }
  }
}'

PauseWebhook

POST /webhook.WebhookService/PauseWebhook

PauseWebhook sets a webhook to inactive. Paused webhooks are skipped during event fan-out -- no new deliveries are created for them. Existing in-flight deliveries are not cancelled. Errors: NOT_FOUND if the webhook does not exist.

Request

webhook_idstring

UUID of the webhook to pause. Required.

namespacestring

Namespace the webhook belongs to. Required.

reasonstring

Human-readable reason for pausing (stored for audit purposes). Optional.

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

ResumeWebhook

POST /webhook.WebhookService/ResumeWebhook

ResumeWebhook re-activates a paused webhook. Future events will again create deliveries for this webhook. Events pushed while the webhook was paused are not retroactively delivered. Errors: NOT_FOUND if the webhook does not exist.

Request

webhook_idstring

UUID of the webhook to resume. Required.

namespacestring

Namespace the webhook belongs to. Required.

reasonstring

Human-readable reason for resuming. Optional.

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

GetNamespaceStats

POST /webhook.WebhookService/GetNamespaceStats

GetNamespaceStats returns aggregate delivery statistics for a namespace: total/active webhooks, total/successful/failed/pending deliveries, and success rate.

Request

namespacestring

Namespace to get statistics for. Required.

Response

namespacestring

The namespace these stats apply to.

stats.total_webhooksint32

Total number of registered webhooks in this namespace (active + inactive).

stats.active_webhooksint32

Number of currently active (non-paused) webhooks.

stats.total_deliveriesint32

Total number of deliveries ever created in this namespace.

stats.successful_deliveriesint32

Number of deliveries in terminal SUCCESS state.

stats.failed_deliveriesint32

Number of deliveries in terminal FAILED state.

stats.pending_deliveriesint32

Number of deliveries in PENDING, SENDING, or RETRYING state.

stats.success_ratedouble

Overall delivery success rate as a decimal between 0.0 and 1.0. Computed as successful_deliveries / total_deliveries. 0.0 if no deliveries.

Request
curl -X POST http://localhost:8080/webhook.WebhookService/GetNamespaceStats \
  -H "Content-Type: application/json" \
  -d '{
  "namespace": "production"
}'
Response
{
  "stats": {
    "total_webhooks": 12,
    "active_webhooks": 10,
    "total_deliveries": 5420,
    "successful_deliveries": 5200,
    "failed_deliveries": 120,
    "pending_deliveries": 100,
    "success_rate": 0.96
  }
}

GetTemplateFunctions

POST /webhook.WebhookService/GetTemplateFunctions

GetTemplateFunctions returns the list of Go template functions available for payload transformation in subscriptions. Each entry includes the function name and a description of its behavior.

Response

functionsTemplateFunction[]

Available template functions with names and descriptions.

total_countint32

Total number of available functions.

Request
curl -X POST http://localhost:8080/webhook.WebhookService/GetTemplateFunctions \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "total_count": 42
}
v1.2.1 · Built on April 10, 2026