--- title: Replay webhook deliveries description: Queue past events again for a webhook, by ID or by time range. doc_version: 0.1.0-preview last_updated: 2026-09-14 --- # Replay webhook deliveries `POST /webhooks/{webhook}:replay` Queue past events again for a webhook, by ID or by time range. **Permission:** Cluster key, or a scoped key with write on every collection that the webhook covers. [API key types and authentication](/engine/reference/authentication.md). 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. ## Example request ```http POST /webhooks/acme-status:replay HTTP/1.1 Host: engine.example.com Authorization: Bearer Content-Type: application/json Idempotency-Key: 8f3c1e2a-4b5d-6e7f-8091-a2b3c4d5e6f7 { "since": "2026-10-06T00:00:00Z", "until": "2026-10-06T12:00:00Z", "only_failed": true } ``` ## Path parameters ### `webhook` **string · required** Webhook ID with the whk_ prefix, or the webhook’s name. ## Headers ### `Idempotency-Key` **string · optional · nullable** 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_ids` **array · optional · nullable** 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_failed` **boolean · optional** Queue only events that this webhook already tried and that ended failed. Default false. Default: `false`. ### `since` **string (date-time) · optional · nullable** Queue the events that occurred at or after this time, as an ISO 8601 timestamp. Send this or event_ids, not both. ### `until` **string (date-time) · optional · nullable** Queue only the events that occurred before this time. Default now. Send it only with since. ## Responses ### 202 · Accepted The events are queued. Watch the delivery log. Content type: `application/json`. #### Response headers ##### `x-engine-request-id` **string · required** The Engine request ID. Retain it when investigating a failed or unexpected request. ##### `x-request-id` **string · required** The X-Request-Id you sent, echoed when it is a valid ID. Otherwise, the Engine request ID. ```json { "queued": 42 } ``` #### Response fields ##### `queued` **integer · required** Number of events queued. An event that was already queued stays queued once and is not counted again. ## Errors [Error format and retry guidance](/engine/reference/errors.md). ### 400 · `invalid_request` A field, path, parameter, or conditional request rule is invalid. Correct the request. Unknown fields are rejected. ```json { "error": { "code": "invalid_request", "message": "A field, path, parameter, or conditional request rule is invalid.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 401 · `unauthenticated` The API key is missing, invalid, or revoked. Send an active key in Authorization: Bearer or X-API-Key. ```json { "error": { "code": "unauthenticated", "message": "The API key is missing, invalid, or revoked.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 403 · `forbidden` The key can see the resource but lacks permission for this operation. Use a key with the required action or scope kind. ```json { "error": { "code": "forbidden", "message": "The key can see the resource but lacks permission for this operation.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 404 · `not_found` The resource is absent, deleted, or outside this key’s scope. Check the identifier and the key’s namespace and collection scope. ```json { "error": { "code": "not_found", "message": "The resource is absent, deleted, or outside this key’s scope.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 409 · `webhook_disabled` The webhook is disabled, so Replay cannot queue events. Enable it with Update webhook, then retry. ```json { "error": { "code": "webhook_disabled", "message": "The webhook is disabled, so Replay cannot queue events.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 409 · `idempotency_conflict` This idempotency key was already used with a different request body. Reuse the original body for a retry, or choose a new key for a new operation. ```json { "error": { "code": "idempotency_conflict", "message": "This idempotency key was already used with a different request body.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 413 · `request_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. Reduce the JSON body. Use upload or a URI source for larger file content. ```json { "error": { "code": "request_too_large", "message": "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.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 503 · `temporarily_unavailable` A dependency, cluster readiness condition, or capacity limit prevents this operation. Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write. ```json { "error": { "code": "temporarily_unavailable", "message": "A dependency, cluster readiness condition, or capacity limit prevents this operation.", "request_id": "req_example", "retryable": true, "details": {} } } ``` ### 500 · `internal_error` An unexpected server failure prevented this request from completing. Retain request_id for investigation. Follow retryable before retrying a write. ```json { "error": { "code": "internal_error", "message": "An unexpected server failure prevented this request from completing.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ## Other request languages ### cURL ```bash curl -sS -X POST "$GRAPHON_ENGINE_URL/webhooks/acme-status:replay" \ -H "Authorization: Bearer $GRAPHON_ENGINE_API_KEY" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: 8f3c1e2a-4b5d-6e7f-8091-a2b3c4d5e6f7' \ --data-raw '{ "since": "2026-10-06T00:00:00Z", "until": "2026-10-06T12:00:00Z", "only_failed": true }' ``` ### Python ```python import json import os import urllib.request request = urllib.request.Request( os.environ["GRAPHON_ENGINE_URL"] + "/webhooks/acme-status:replay", data=json.dumps({"since": "2026-10-06T00:00:00Z", "until": "2026-10-06T12:00:00Z", "only_failed": True}).encode("utf-8"), headers={ "Authorization": "Bearer " + os.environ["GRAPHON_ENGINE_API_KEY"], "Content-Type": "application/json", "Idempotency-Key": "8f3c1e2a-4b5d-6e7f-8091-a2b3c4d5e6f7", }, method="POST", ) with urllib.request.urlopen(request) as response: print(response.read().decode()) ``` ### JavaScript ```javascript const response = await fetch(process.env.GRAPHON_ENGINE_URL + "/webhooks/acme-status:replay", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GRAPHON_ENGINE_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "8f3c1e2a-4b5d-6e7f-8091-a2b3c4d5e6f7", }, body: JSON.stringify({"since":"2026-10-06T00:00:00Z","until":"2026-10-06T12:00:00Z","only_failed":true}), }); console.log(response.status, await response.text()); ``` ## Sitemap See the full [sitemap](/sitemap.md) for all pages.