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.

Response

deliveriesWebhookDelivery[]

Deliveries matching the filter criteria, newest first.

paginationPaginationResponse

Pagination metadata.

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
  }
}'

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", "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"
  }
}