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 theintegrationandintegration-testprofiles. - The fixture creates a synthetic
customer.createdwebhook row inDEADstate plus a processed-webhook idempotency row. Replaying the webhook is safe: the unified dispatcher treatscustomer.createdas 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
50ad0d7added the smoke fixture and recovery tests. - Backend pipeline
2628508559failed inmaven-testafter tests passed because SpotBugs flaggedVA_FORMAT_STRING_USES_NEWLINEin the synthetic JSON payload builder. - Backend commit
678e560replaced the text-block formatted payload with a compact JSON string builder. - Backend pipeline
2628535943succeeded: 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/deadreturned HTTP 201 and created aDEADcustomer.createdrow with error codeEP7_T3_SMOKE_FIXTURE.GET /v1/internal/stripe-webhooks?status=DEADreturned the fixture row.- Unauthenticated
POST /v1/internal/stripe-webhooks/id/{id}/replayreturned HTTP 401. - Authenticated replay returned HTTP 200 and moved the fixture row to
IGNORED. GET /v1/internal/stripe-webhooks?status=IGNOREDshowed the replay result.GET /v1/admin/processed-webhooks?eventType=customer.createdreturned 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
DEADcustomer.createdrow 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
IGNOREDand cleared the error display. - Processed Webhooks screen showed
customer.createdidempotency 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.