Replaying Events

Retained events can be replayed whether a previous delivery succeeded, failed, or never existed. Manual replay currently requires a plan whose effective plan ceiling permits it (Guard, Sentinel, or Bastion). Scout is denied by the API; the earlier all-plans changelog claim conflicts with that guard and needs a product decision.

How to replay

1. Open an event and choose Choose destinations, or select up to 50 events in the Events list and choose Replay selected.
2. Select active destinations in the picker. Newly added destinations are available even if they are not linked to the original source.
3. Choose Replay to selected destinations.

Each event is sent only to selected destinations in its own project. Inactive, deleted, and other-project destinations are rejected. Existing in-flight deliveries are skipped. Events with failed source verification are blocked from replay; request a new provider delivery after correcting the source configuration.

A replay creates separate delivery records under the same event and preserves the original history. It uses the workspace's normal attempt count and retry schedule. An open destination circuit holds the new delivery until resumed.

Payload and authentication

Replay sends the stored raw body bytes. It preserves supported provider signature and event identity headers, and adds fresh Watchtower authentication independently. Credentials and transport headers are excluded; see signature verification for the forwarding allowlist.

Original signatures are not refreshed. Delayed Stripe replay can fail the provider's timestamp tolerance even when the body and signature match. Keep that validation enabled on provider endpoints. Use a separate historical-processing endpoint that validates Watchtower's fresh HMAC and timestamp and requires verified ingestion. Legacy workspaces without a signing secret must initialize one in Settings → Security first.

Your handler must remain idempotent. Manual replay can repeat an already completed business action; the stable provider event ID still identifies the same event.

API and repeated actions

Both POST /workspaces/:workspaceId/events/:eventId/replay and POST /workspaces/:workspaceId/events/replay-batch accept a JSON body:

{
  "requestId": "3a5cb131-6fb5-4fd8-9ef4-751955a68a33",
  "destinationIds": ["d907d031-665a-4b46-83a0-fafcba0ddc33"]
}

Batch requests additionally require eventIds (1–50 UUIDs). All events must belong to the named workspace. If destinationIds is omitted, the API uses the source's current active destination links. The dashboard always asks you to select destinations explicitly.

Reuse requestId when retrying an uncertain response. Idempotency is scoped to the caller, request ID, event, and destination while the event is retained. Workspace and caller UUIDs use their canonical database representation. Equivalent UUID spellings share the same tuple, which cannot create another delivery even after completion. Use a new UUID for a deliberate later replay. Changing destinations with the same ID can create deliveries for newly selected destinations. Queue failures leave a durable pending record; retry the same request, or the outbox reconciler recovers it after five minutes. Delivery remains at least once, so receiver idempotency is still required.

Responses include event counts replayed and skipped, plus deliveriesQueued, deliveriesHeld (open circuits), and alreadyRequested. A repeated action may return an existing record without scheduling another attempt.

Event retention

Replay depends on retained payloads. Current defaults are Scout 1 day, Guard 7 days, Sentinel 30 days, and Bastion 90 days; check your workspace's actual plan for grandfathered limits. Once cleanup removes an event it cannot be replayed. Existing events that lost non-UTF-8 bytes before lossless storage was introduced cannot recover those bytes retroactively.