Skip to content

Stripe Webhook Recovery Verification

Last audited: 2026-06-25.

EP7-T3 verifies that support can recover a stuck Stripe webhook from the admin surface without database access.

Scope

  • Backend admin webhook inbox and replay endpoints: /v1/internal/stripe-webhooks
  • Backend processed-webhook idempotency browser: /v1/admin/processed-webhooks
  • Web-admin Stripe Webhooks and Processed Webhooks screens
  • Runbook: Admin webhook replay and problem reports

Implementation Result

  • Backend added an integration-only smoke fixture endpoint: POST /v1/internal/stripe-webhooks/smoke-test/dead.
  • The fixture route is hidden from OpenAPI, guarded by ROLE_ADMIN, and only active under the integration and integration-test profiles.
  • The fixture creates a synthetic customer.created webhook row in DEAD state plus a processed-webhook idempotency row. Replaying the webhook is safe: the unified dispatcher treats customer.created as ignored and does not mutate payment, subscription, user, or Stripe Connect state.
  • Web-admin already had the required Stripe Webhooks and Processed Webhooks screens, so no frontend code change was required for EP7-T3.

Local Verification

  • Targeted backend tests: mvn -q -Dtest=StripeWebhookOpsIntegrationTest,AdminProcessedWebhooksIntegrationTest,StripeWebhookOpsServiceTest -Djacoco.skip=true test
  • Full backend CI-equivalent verification: mvn -B verify
  • Full verify result: 5537 tests, 0 failures, 0 errors, 6 skipped; Jacoco passed; SpotBugs found 0 bugs.

Integration Deployment

  • Backend commit 50ad0d7 added the smoke fixture and recovery tests.
  • Backend pipeline 2628508559 failed in maven-test after tests passed because SpotBugs flagged VA_FORMAT_STRING_USES_NEWLINE in the synthetic JSON payload builder.
  • Backend commit 678e560 replaced the text-block formatted payload with a compact JSON string builder.
  • Backend pipeline 2628535943 succeeded: environment contract, gitleaks, semgrep, Maven build artifacts, Maven test, API backwards compatibility, and integration deploy all passed.

Live Integration Smoke

Environment:

  • Admin UI: https://admin-integration.mamnajem.pl
  • API: https://integration.mamnajem.pl/v1
  • Disposable Cognito admin with MFA was used for the smoke check.

API evidence:

  • POST /v1/internal/stripe-webhooks/smoke-test/dead returned HTTP 201 and created a DEAD customer.created row with error code EP7_T3_SMOKE_FIXTURE.
  • GET /v1/internal/stripe-webhooks?status=DEAD returned the fixture row.
  • Unauthenticated POST /v1/internal/stripe-webhooks/id/{id}/replay returned HTTP 401.
  • Authenticated replay returned HTTP 200 and moved the fixture row to IGNORED.
  • GET /v1/internal/stripe-webhooks?status=IGNORED showed the replay result.
  • GET /v1/admin/processed-webhooks?eventType=customer.created returned processed-webhook idempotency records with the event type and processed time visible and the raw event ID hidden.

Browser evidence:

  • Web-admin login with admin MFA succeeded.
  • Stripe Webhooks screen showed a DEAD customer.created row with hidden event ID, hidden context, EP7_T3_SMOKE_FIXTURE, and an enabled replay action.
  • Entering a replay reason and clicking replay changed the same row to IGNORED and cleared the error display.
  • Processed Webhooks screen showed customer.created idempotency records and kept raw processed event IDs hidden until a reveal reason is supplied.

Support Decision

EP7-T3 is complete. A Product Owner can recover a test dead webhook in integration without database access. Production replay remains gated by the runbook criteria and second-operator review for payment, refund, dispute, and subscription revocation events.