DeliveryService

Base URL

DeliveryService provides read access to delivery history and manual retry control. Deliveries are created automatically when an event is pushed. Each delivery tracks its status (pending -> sending -> success/failed/retrying/expired), HTTP response code, response body (up to 1 KB by default, 1 MB if capture_response_body is enabled), error classification, and per-attempt history.

GetDeliveryStatus

POST /webhook.DeliveryService/GetDeliveryStatus

GetDeliveryStatus returns full details of a single delivery, including request body, response body, response code, error category, and retry state. Errors: NOT_FOUND if the delivery_id does not exist in the given namespace.

Request

delivery_idstring

UUID of the delivery to retrieve. Required.

namespacestring

Namespace the delivery belongs to. Required.

Response

deliveryWebhookDelivery

Full delivery details including request/response bodies and error info.

Request

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

ListDeliveries

POST /webhook.DeliveryService/ListDeliveries

ListDeliveries returns delivery records for a namespace, optionally filtered by webhook_id or event_id. Ordered by created_at descending. Paginated.

Request

namespacestring

Namespace to list deliveries from. Required.

webhook_idstring

Filter by webhook UUID. Optional.

event_idstring

Filter by event UUID. Optional.

paginationPaginationRequest

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

statusstring

Filter by delivery status. Optional.

error_categorystring

Filter by error classification. Optional.

subscription_idstring

Filter by subscription UUID. Optional.

created_afterTimestamp

Filter to deliveries created at or after this timestamp.

created_beforeTimestamp

Filter to deliveries created at or before this timestamp.

prepare_retrybool

When true, snapshot all matching delivery IDs (up to 10,000) into a batch job and return a retry_id in the response. Pass that ID to RetryDeliveries to retry the exact set that matched this query.

Response

deliveriesWebhookDelivery[]

Deliveries matching the filter criteria, newest first.

paginationPaginationResponse

Pagination metadata.

retry_idstring

Batch ID for deterministic retry. Only populated when prepare_retry=true was set in the request. Pass to RetryDeliveries.

Request

curl -X POST http://localhost:8080/webhook.DeliveryService/ListDeliveries \
  -H "Content-Type: application/json" \
  -d '{
  "namespace": "production",
  "webhook_id": "550e8400-e29b-41d4-a716-446655440000",
  "pagination": {
    "limit": 20
  },
  "status": "failed",
  "error_category": "server_error"
}'

RetryDelivery

POST /webhook.DeliveryService/RetryDelivery

RetryDelivery re-enqueues deliveries for processing. Can target a specific delivery_id, all failed/pending deliveries for a webhook_id, or both. Set force=true to retry even successful deliveries. Returns the count and IDs of deliveries that were re-enqueued.

Request

namespacestring

Namespace. Required.

delivery_idstring

UUID of a specific delivery to retry. Optional.

webhook_idstring

UUID of a webhook -- retry all its failed/pending deliveries. Optional.

forcebool

When true, retry even successful deliveries. Default: false. Use with caution: this causes duplicate delivery to the target endpoint.

Response

retried_countint32

Number of deliveries that were re-enqueued.

delivery_idsstring[]

UUIDs of the deliveries that were re-enqueued.

Request

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

Response

{
  "retried_count": 1,
  "delivery_ids": [
    "d-550e8400-e29b-41d4-a716-446655440000"
  ]
}

GetDeliveryAttempts

POST /webhook.DeliveryService/GetDeliveryAttempts

GetDeliveryAttempts returns the per-attempt history for a delivery, ordered by timestamp. Each attempt includes response_time, response_code, error_message, and error_category. Errors: INVALID_ARGUMENT if delivery_id is empty.

Request

delivery_idstring

UUID of the delivery to get attempts for. Required.

Response

attempts[].attempt_idstring

Server-generated UUID for this attempt.

attempts[].delivery_idstring

UUID of the parent delivery this attempt belongs to.

attempts[].webhook_idstring

UUID of the target webhook.

attempts[].successbool

Whether this attempt resulted in a successful delivery (response code matched expected_status_codes).

attempts[].response_timeint32

Round-trip time in milliseconds from sending the request to receiving the full response (or timeout/error). 0 if no connection was established.

attempts[].response_codeint32

HTTP response status code. 0 if no response was received (timeout, connection refused, DNS error, etc.).

attempts[].error_messagestring

Error message describing the failure. Empty string on success. Contains the raw error from the HTTP client (e.g., "context deadline exceeded", "connection refused", "no such host").

attempts[].error_categorystring

Classified error category for this attempt. Values: "success", "client_error", "server_error", "timeout", "connection_refused", "network_error", "dns_error", "tls_error", "unexpected_status", "unknown".

attempts[].timestampTimestamp

When this attempt was made.

Request

curl -X POST http://localhost:8080/webhook.DeliveryService/GetDeliveryAttempts \
  -H "Content-Type: application/json" \
  -d '{
  "delivery_id": "d-550e8400-e29b-41d4-a716-446655440000"
}'

Response

{
  "attempts[]": {
    "attempt_id": "a-110e8400-e29b-41d4-a716-446655440000",
    "success": true,
    "response_time": 245,
    "response_code": 200,
    "error_category": "success",
    "timestamp": "2025-01-15T10:30:05Z"
  }
}

RetryDeliveries

POST /webhook.DeliveryService/RetryDeliveries

RetryDeliveries executes a deterministic batch retry of deliveries whose IDs were previously snapshotted via ListDeliveries with prepare_retry=true. Each delivery is reset to pending and re-enqueued for HTTP delivery. The batch is processed asynchronously via a River job; poll GetRetryStatus for progress. Errors: NOT_FOUND if the retry_id does not exist or has expired. Errors: FAILED_PRECONDITION if the batch is not in 'pending' status.

Request

retry_idstringrequired

Batch ID returned by ListDeliveries when prepare_retry=true.

Response

retry_idstring

Batch ID for polling status.

totalint32

Total number of deliveries that will be retried.

statusstring

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

Request

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

GetRetryStatus

POST /webhook.DeliveryService/GetRetryStatus

GetRetryStatus returns the current progress of a batch retry operation. Errors: NOT_FOUND if the retry_id does not exist or has expired.

Request

retry_idstringrequired

Batch ID returned by RetryDeliveries or ListDeliveries.

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.DeliveryService/GetRetryStatus \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "batch": {
    "status": "processing"
  }
}

CancelRetry

POST /webhook.DeliveryService/CancelRetry

CancelRetry aborts a batch retry that is pending or in progress. Items already processed are not rolled back. Errors: NOT_FOUND if the retry_id does not exist. Errors: FAILED_PRECONDITION if the batch is already completed or cancelled.

Request

retry_idstringrequired

Batch ID to cancel.

Response

statusstring

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

Request

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