Replay deliveries

replay is the primary mutating command in the agentic surface. It re-delivers real events to a real target, a deliberate re-send, distinct from the forwarder's automatic retries. Every replayed delivery has the same downstream effect as the original webhook.

Before you replay#

Replay follows the universal safe-mutation pattern: confirm write scope, resolve stable IDs (arrive here from Diagnose webhooks), preview, make it idempotent, gate bulk behind --yes, then wait. This page covers the replay-specific parts: choosing a selector, reading the dry-run, and branching on the wait exit code. --forwarder is always required; a replay targets exactly one forwarder.

Always dry-run first#

--dry-run resolves the selector against the index and returns a count without creating a job. It is the only safe way to learn a replay's blast radius.

Copyrepost replay \
  --forwarder prod-api \
  --bucket stripe-prod \
  --query 'response_status:500 AND path:/stripe/*' \
  --since 30m \
  --dry-run \
  --json

Copy{
  "schema": "repost.replay.create/v1",
  "data": {
    "status": "DRY_RUN",
    "dry_run": true,
    "would_replay": 42
  }
}

Choose a selector#

A replay sources its events one of four ways. The selector you pass determines the source_type on the resulting job.

Execute the replay#

Once the dry-run count is right, drop --dry-run and confirm. Keep --idempotency-key and set --rate if the target is sensitive to burst.

Copyrepost replay \
  --forwarder prod-api \
  --bucket stripe-prod \
  --query 'response_status:500 AND path:/stripe/*' \
  --since 30m \
  --rate 25 \
  --idempotency-key "incident-4821-stripe-500s" \
  --yes \
  --json

Copy{
  "schema": "repost.replay.create/v1",
  "data": {
    "job_id": "rpl_01JZ9F2K7M",
    "status": "PENDING",
    "dry_run": false
  }
}

The job is accepted asynchronously and starts in PENDING. Capture job_id. Every follow-up (status, wait, pause, cancel) takes it.

Idempotent retries#

If a replay call times out or its connection drops, re-run the identical command. With the same --idempotency-key, the API re-attaches to the original job instead of creating a second one and sets deduplicated:

Copy{
  "schema": "repost.replay.create/v1",
  "data": { "job_id": "rpl_01JZ9F2K7M", "status": "IN_PROGRESS", "deduplicated": true }
}

Treat deduplicated: true as success: the work is already running under job_id. Without a key, a blind retry double-delivers, so always set one for bulk replays.

Wait for the result#

replay wait polls until the job is finalized, then exits with a code that encodes the outcome. Branch on the exit code and the boolean finalized field, never on the status string.

Copyrepost replay wait rpl_01JZ9F2K7M --max-wait 5m --json

Copy{
  "schema": "repost.replay.status/v1",
  "data": {
    "job_id": "rpl_01JZ9F2K7M",
    "status": "COMPLETED",
    "finalized": true,
    "total": 42,
    "pending": 0,
    "succeeded": 41,
    "failed": 1,
    "created_at": "2026-06-19T09:02:11Z",
    "completed_at": "2026-06-19T09:03:44Z"
  }
}

Job lifecycle#

A replay job moves through these states. wait returns the moment finalized becomes true: at COMPLETED, FAILED, or CANCELLED.

CopystateDiagram-v2
    [*] --> PENDING: replay accepted
    PENDING --> STARTING
    STARTING --> IN_PROGRESS
    IN_PROGRESS --> PAUSED: pause
    PAUSED --> IN_PROGRESS: resume
    IN_PROGRESS --> COMPLETED: all delivered
    IN_PROGRESS --> FAILED: errors exceed threshold
    IN_PROGRESS --> CANCELLED: cancel
    PAUSED --> CANCELLED: cancel
    COMPLETED --> [*]
    FAILED --> [*]
    CANCELLED --> [*]

Manage a running job#

While a job runs, inspect or steer it by job_id.

Copyrepost replay status rpl_01JZ9F2K7M --json

status, list, and the actions return repost.replay.status/v1, repost.replay.list/v1, and repost.replay.action/v1 respectively. list is created_at-descending and paginates with has_more. Raise --limit to see older jobs. Use pause/resume to throttle a replay mid-incident; Guard a deployment shows the full pause-deploy-resume loop.

Continue#