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:
integrationorproduction - Stripe event ID
- Backend
requestId,correlationId, andspawnId, if present - Webhook status, attempt count, last error code, and last error message
- Affected
payment_request_id,payment_intent_id,subscription_id, orcustomer_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
RETRYABLEorDEAD. - 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