Graphon Engine

Replay webhook deliveries

Queue past events again for a webhook, by ID or by time range.

POST/webhooks/{webhook}:replay

PermissionCluster key, or a scoped key with write on every collection that the webhook covers. Key scopes and actions.

  • Send exactly one of event_ids and since. until goes only with since.
  • Engine queues each selected event in the webhook’s scope and types that it still holds (30 days), and skips the rest. A range can reach back before the webhook’s create.
  • A replayed event keeps its id and its bytes, in a new batch with a new webhook-id. Deduplicate by event id.
  • Replayed events go out before newer queued events of the same webhook, up to 500 to a POST. A large replay delays live events, so replay a narrow range.
  • Idempotency-Key is optional. Retry the same replay with the same key and body.

Path parameters

webhookstringrequired

Webhook ID with the whk_ prefix, or the webhook’s name.

Headers

Idempotency-Keystringoptionalaccepts null

Unique key for this logical operation. Reuse it only with the same request for retries. Retained for 86,400 seconds. A changed body returns idempotency_conflict.

Request body

event_idsarray<string>optionalaccepts null

evt_ IDs of the events to queue again. Send this or since, not both. An ID outside the scope, types, or 30-day retention is skipped.

only_failedbooleanoptional

Queue only events that this webhook already tried and that ended failed. Default false.

Default: false

sincestring (date-time)optionalaccepts null

Queue the events that occurred at or after this time, as an ISO 8601 timestamp. Send this or event_ids, not both.

untilstring (date-time)optionalaccepts null

Queue only the events that occurred before this time. Default now. Send it only with since.

Responses

202Accepted

The events are queued. Watch the delivery log.

application/json

Response headers

x-engine-request-idstringrequired

The Engine request ID. Retain it when investigating a failed or unexpected request.

x-request-idstringrequired

The X-Request-Id you sent, echoed when it is a valid ID. Otherwise, the Engine request ID.

queuedintegerrequired

Number of events queued. An event that was already queued stays queued once and is not counted again.

Errors

Select an error in the response example to see its JSON body. See error handling for the common error format.

400invalid_request

A field, path, parameter, or conditional request rule is invalid.

What to do: Correct the request. Unknown fields are rejected.

401unauthenticated

The API key is missing, invalid, or revoked.

What to do: Send an active key in Authorization: Bearer or X-API-Key.

403forbidden

The key can see the resource but lacks permission for this operation.

What to do: Use a key with the required action or scope kind.

404not_found

The resource is absent, deleted, or outside this key’s scope.

What to do: Check the identifier and the key’s namespace and collection scope.

409webhook_disabled

The webhook is disabled, so Replay cannot queue events.

What to do: Enable it with Update webhook, then retry.

409idempotency_conflict

This idempotency key was already used with a different request body.

What to do: Reuse the original body for a retry, or choose a new key for a new operation.

413request_too_large

The JSON body exceeds the route limit: 6,291,456 bytes on :answer and research, 4,194,304 bytes on :search and :read-spans, and 1,048,576 bytes elsewhere.

What to do: Reduce the JSON body. Use upload or a URI source for larger file content.

503temporarily_unavailable

A dependency, cluster readiness condition, or capacity limit prevents this operation.

What to do: Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write.

500internal_error

An unexpected server failure prevented this request from completing.

What to do: Retain request_id for investigation. Follow retryable before retrying a write.

Was this page helpful?
View as Markdown