--- title: "Re-queue a failed delivery" method: POST path: "/webhooks/{webhookId}/events/{eventId}/retry" tags: ["Webhooks"] --- # Re-queue a failed delivery `POST /webhooks/{webhookId}/events/{eventId}/retry` ## Request - Base URL: `https://inkseal.net/api/v1` - URL: `https://inkseal.net/api/v1/webhooks/{webhookId}/events/{eventId}/retry` - Auth: HTTP bearer Reopen a delivery that gave up, after the receiving endpoint has been repaired. **Precondition.** Only a terminal failure can be retried: the delivery must have `status: "failed"` with no `nextRetryAt` scheduled, which `GET /webhooks/{webhookId}/events` reports as `terminal: true`. A delivery that succeeded, is still pending, or is merely between automatic attempts answers 409 `not_retryable`. **What it does.** The delivery is reset to `pending`, its **attempt counter is set back to zero**, and its recorded response status, response body, and delivery timestamp are cleared. It is then queued for immediate dispatch, which gives it a fresh full run of the automatic policy rather than one last attempt. The per-attempt records written against it are kept, so the history of what already failed is not erased. **The automatic policy this sits alongside.** A delivery is attempted up to 6 times before it becomes terminal. Between attempts the delay doubles, starting at 60 seconds and capped at 1 hour: roughly 1m, 2m, 4m, 8m, 16m, 32m. A delivery is also marked terminal immediately, without consuming the remaining attempts, when the target URL fails the SSRF check at send time, since retrying a destination that must never be contacted is pointless. Because the delivery keeps the same event id, a consumer deduplicating on `X-InkSeal-Event-Id` sees a manual retry as the same event it may already have processed. Accepts an `Idempotency-Key`; a retry with the same key replays the original response instead of reopening the delivery twice. ## Headers - `Idempotency-Key` string ## Response `200` The delivery has been reset and queued. - object - `data` WebhookDeliveryRetryResult, required: The delivery after being reopened: attempt counter cleared and queued for immediate dispatch. - `id` integer, required - `status` 'pending', required: Always `pending`: the delivery is back in the queue with a fresh run of the 6-attempt policy ahead of it. ## Other responses - `400`: The request is malformed or the resource is in the wrong state for a synchronous check. Codes: `validation_error`, `invalid_body`, `invalid_parameter`, `invalid_idempotency_key`, `invalid_event_id`, `invalid_file`, `invalid_url`, `invalid_status`, `key_mismatch`, `no_signers`, `not_completed`, `envelope_exists`, `document_not_ready`, `upload_failed`. - `401`: The credential is missing, malformed, unknown, expired, revoked, or past its rotation grace window. Code: `unauthorized`. Every authentication failure is deliberately indistinguishable. - `403`: The credential is valid but may not do this. Codes: `insufficient_scope` (the route's scopes are not all held; `details` names `requiredScopes` and `missingScopes`), `forbidden` (the capability check on the resolved resource failed), `scope_escalation` (a grant wider than the caller's own was requested). - `404`: The resource does not exist, was deleted, or belongs to another workspace. Code: `not_found`. The three cases are answered identically on purpose, so a 404 never confirms that an identifier exists elsewhere. - `409`: The resource's state forbids this transition, or another request owns the work. Codes: `invalid_state`, `invalid_status`, `credential_state`, `limit_exceeded`, `envelope_missing`, `not_retryable`, `owner_unavailable`, `workspace_unavailable`, `detection_not_completed`, `document_in_use`, `version_conflict`, `document_processing`, `document_processing_failed`, `normalized_pdf_unavailable`, `pages_not_rendered`, `document_not_ready`, `idempotency_in_progress` (which also carries `Retry-After`), `payment_replayed` (a USDC payment signature presented twice), `payment_pending` (a USDC settlement whose outcome is not yet known). - `422`: The request parsed but its content is not acceptable. Codes: `validation_error` (envelope configuration, with an `issues` array in `details`), `invalid_envelope`, `envelope_not_ready`, `document_page_limit`, `idempotency_key_reuse`. - `429`: A limit was reached. Codes: `rate_limited` (the credential's per-bucket HTTP limit, or the per-workspace detection throttle), `workspace_limit_exceeded` (a workspace content or send limit; `details.limit` names it), `daily_budget_exceeded` (the workspace's daily detection budget). The four rate-limit headers are sent on this response and on no successful one, so a client cannot read its remaining budget without being refused. Retrying after `Retry-After` is always safe: a rate-limit refusal happens before the handler runs. - `503`: A dependency the request needs is unreachable and nothing was changed. Codes: `queue_unavailable` (a background job could not be enqueued; retry the call), `billing_unavailable` (Stripe would not open a checkout session; nothing was charged, retry the call), `service_unavailable` (the rate-limit store is down, so the request was refused before running). --- [API](https://skmtc.dev/inkseal/apis/inkseal-api.md) · [All operations](https://skmtc.dev/inkseal/apis/inkseal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/inkseal/apis/inkseal-api/revisions/c440c981d578?raw)