Skip to content

Admin Webhook Replay And Problem Reports

Last audited: 2026-06-25.

Use this workflow when a Stripe webhook is DEAD, stuck in RETRYABLE, or linked to a user problem report.

Required Evidence

  • Environment: integration or production
  • Stripe event ID
  • Backend requestId, correlationId, and spawnId, if present
  • Webhook status, attempt count, last error code, and last error message
  • Affected payment_request_id, payment_intent_id, subscription_id, or customer_id
  • User-reported symptom and problem report ID, if applicable

Inspect

curl -fsS "$API_BASE_URL/v1/internal/stripe-webhooks?status=DEAD&size=50" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Filter by exact IDs when known:

curl -fsS "$API_BASE_URL/v1/internal/stripe-webhooks?payment_request_id=$PAYMENT_REQUEST_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Replay Criteria

Replay only when all are true:

  • The root cause is fixed or known to be transient.
  • The event type is idempotent in the current backend.
  • The database state still expects the event.
  • A second operator has reviewed production replays for payment, refund, dispute, or subscription revocation events.

Do not replay if the event would duplicate a receipt, revoke an active subscription incorrectly, or move a payment backwards without explicit correction notes.

Replay

curl -fsS -X POST "$API_BASE_URL/v1/internal/stripe-webhooks/$STRIPE_EVENT_ID/replay" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"incident INC-0000: root cause fixed, idempotency checked"}'

Verify the row becomes PROCESSED or IGNORED, then verify the user-facing object: payment request, receipt, subscription, or connected account.

If the web-admin table shows only the redacted row ID, replay by row ID:

curl -fsS -X POST "$API_BASE_URL/v1/internal/stripe-webhooks/id/$WEBHOOK_ROW_ID/replay" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"incident INC-0000: root cause fixed, idempotency checked"}'

Integration Smoke Fixture

Use this only in integration to prove the recovery path without creating a real Stripe incident:

curl -fsS -X POST "$API_BASE_URL/v1/internal/stripe-webhooks/smoke-test/dead" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"EP7-T3 recovery smoke"}'

The endpoint is hidden from OpenAPI, requires admin auth, and is active only under the integration and integration-test profiles. It creates a synthetic DEAD customer.created webhook row and a processed-webhook fixture row. Replay is expected to move the webhook row to IGNORED; it must not mutate payment, subscription, user, or Stripe Connect state.

Do not use this fixture in production. The route is not active there.

Stop Conditions

  • Replay returns RETRYABLE or DEAD.
  • New 5xx, New Relic issue/alert, or CloudWatch backend ERROR appears after replay.
  • The same Stripe event changes unrelated user/account state.

Escalate to incident owner and stop manual replay until the handler is patched or a database correction plan is approved.

Problem Report Linkage

When a user report is involved, add these incident notes:

  • Problem report ID and reporter user ID
  • Affected account/user IDs
  • Stripe event ID
  • Replay decision and operator
  • Final user-visible state