Replay events to a webhook subscription
Re-delivers historical events to the subscription's endpoint. Useful for recovering from outages or backfilling a new subscription.
BEHAVIOR: - Events are delivered in chronological order. - Each replayed event is tracked as a new WebhookDelivery. - Replay respects the subscription's retry policy. - Concurrent replays to the same subscription are NOT allowed.
LIMITS: - Maximum 1000 events per replay request (the max_events cap). - Use from/to to control the replay window.
COMPLETENESS — ALL-OR-NARROW SELECTION, BEST-EFFORT ENQUEUE (NORMATIVE): on a 202 accepted response the server has SELECTED every deliverable event in the [from, to] window — selection is COMPLETE for the window, never a partial selection with an implied continuation. Selection completeness is all-or-narrow: the selection is complete, or the request is rejected 400 per the max_events / SCAN LIMIT rules below. There is NO continuation position in the API: the accepted response (replay_id / events_queued / estimated_completion_seconds) carries no cursor or last-replayed marker, and max_events is NOT a resumable page cursor.
Enqueue is BEST-EFFORT: the server enqueues the selected events for
delivery best-effort and events_queued reports the number of
deliveries successfully ENQUEUED, which MAY be fewer than the number
of events selected — because of a transient backend failure, OR for an
intended reason: the subscription was concurrently deactivated
(paused / disabled / deleted), or an event was filtered by a
delivery-time guard (e.g. the ownership boundary re-checked at
dispatch), between selection and enqueue. The strong guarantee is the
COMPLETE SELECTION (or a 400), not an atomic all-or-nothing enqueue.
Operators SHOULD treat an unexpectedly low events_queued as worth
investigating — though it may be an intended lifecycle/guard outcome
rather than backend degradation.
Replay is NOT idempotent: each replay ATTEMPTS to enqueue every
selected event as a fresh WebhookDelivery, so retrying after a partial
enqueue MAY duplicate the events that were SUCCESSFULLY enqueued on the
prior attempt (those counted in events_queued).
Selection rules (all-or-narrow): - If the window contains MORE than max_events deliverable events, the
server MUST reject the request with 400 INVALID_REQUEST (no partial
selection). The caller narrows the from/to range, or raises
max_events (up to the 1000 cap), so the whole window fits in one
request.
- If the window exceeds the server's SCAN LIMIT (more candidate events
than the server will scan while evaluating the request), the server
MUST likewise reject with 400 INVALID_REQUEST. The caller narrows the
from/to range. The scan-limit VALUE is server-defined
(implementation-specific; a reference server documents its own limit);
the normative point is the BEHAVIOR — complete-selection-or-400, never
a silently-truncated or implied-continuation selection. - Practical limitation (honest note): because there is no continuation
position, a set of MORE thanmax_events(up to the 1000 cap)
deliverable events sharing a SINGLE timestamp cannot be narrowed by
from/to to fit and must be covered by raisingmax_events; a set
larger than the 1000 cap at one timestamp is beyond what a single
replay can select. For governance events this is effectively
unreachable.
Authorizations
Administrative API key with full system access. Also accepted as an alternative to ApiKeyAuth on an explicit per-operation allowlist — the authoritative list is the union of operations whose security: block declares AdminKeyAuth (consult per-operation security blocks rather than this prose, which has historically drifted as the dual-auth surface expanded). When using AdminKeyAuth on list or fund endpoints, a tenant scoping parameter (typically tenant or tenant_id) is required for scoping (400 if missing) — the per-operation description specifies which. Lookup-style endpoints that uniquely identify a resource by non-tenant key (e.g. GET /v1/admin/budgets/lookup, where the (scope, unit) pair is unique) do NOT require a tenant parameter. Allowlisting is per-operation (exact method:path matching — no prefix matching, no wildcards) so new endpoints do not accidentally inherit admin-accessible status.
Parameters
Path Parameters
Request Body
Responses
Replay accepted (processing asynchronously)