Payment Webhook Go-Live Checklist for Production Launch

A webhook endpoint is production-ready when the team has evidence for failure behavior, not merely one successful request. Payment events can be delayed, repeated, malformed, replayed, or delivered while a dependency is unavailable. Your launch test should prove that those conditions do not create false payment success or duplicate fulfilment.

Use the dashboard Webhook Workbench to send a real test and inspect HTTP status, latency, event ID, attempt, and response summary. Then test application behavior with controlled fixtures in your own environment.

Endpoint and Network

Confirm:

• Public HTTPS endpoint uses a valid certificate.
• POST reaches the intended route without a sign-in redirect.
• Reverse proxy forwards the signature and timestamp headers.
• Request body reaches the verifier as exact bytes.
• Endpoint is not protected by browser session cookies or CSRF designed for forms.
• Rate limits permit expected payment events without allowing unlimited abuse.
• Timeouts are shorter than the sender’s delivery timeout.

The endpoint should perform a small critical path: authenticate, deduplicate, validate, persist, acknowledge. Email, inventory, document generation, and external fulfilment belong in a durable worker after commit.

Authentication and Replay

Run at least these cases:

Test	Expected result
Valid timestamp and signature	Accepted according to order state
Missing signature	401 or equivalent rejection
Modified body	Signature rejection
Stale signed timestamp	Replay rejection
Wrong environment secret	Signature rejection
Rotated secret on all instances	New test succeeds consistently

Never add a “skip verification in production” flag to solve deployment problems. Follow the signed webhook verification guide and fix raw-body handling, proxy headers, clock drift, or secret distribution.

Database Idempotency

Send the same authentic event at least twice. The test passes only when:

1. One webhook receipt exists for the event ID.
2. The order transitions once.
3. Inventory, wallet credit, email, or subscription effect occurs once.
4. The duplicate receives 2xx after the system recognizes it.
5. Concurrent copies are also safe.

An application-level “already seen” check without a database constraint can race across workers. Use a unique index and one transaction as shown in the duplicate webhook fulfilment guide.

Delivery and Recovery

Test four operational failures:

Application returns 500: Verify the delivery record shows the failure and your alert identifies the event ID without exposing secrets.

Endpoint is temporarily unavailable: Restore it and confirm the same event can be accepted safely when delivered again.

Database commits but acknowledgement is lost: The repeated event must be recognized as already processed.

Webhook never resolves the customer page: A backend status check or scheduled reconciliation should recover the known order without creating a new payment attempt.

The webhook delivery monitoring guide explains how to separate transport success from application fulfilment.

Launch Evidence

Create a short launch record:

• Public endpoint hostname and environment
• Secret rotation owner and date
• Replay tolerance and time source
• Database uniqueness migration reference
• Valid-event test ID
• Duplicate-event test ID
• Failed-delivery test result
• Recovery test result
• On-call owner and support runbook
• Rollback or checkout-disable procedure

Protect this evidence. It should contain event references and results, not complete secrets or unnecessary customer information.

After launch, monitor signature rejection rate, response-code distribution, p95 endpoint latency, duplicate-event count, unresolved pending orders, and time from verified event to durable order update. These metrics reveal a broken boundary before support tickets become your primary monitoring system.

Use an explicit launch decision instead of accepting “mostly working” results:

Result	Decision
Valid, duplicate, stale, and recovery tests pass	Eligible for controlled launch
Signature validation differs across application instances	Stop and repair secret or deployment consistency
Duplicate test repeats fulfilment	Stop; this is a financial correctness defect
Endpoint returns 2xx before durable acceptance	Stop; an event can be lost after acknowledgement
Recovery needs a direct database edit	Stop and implement an authorized operational path

Repeat the checklist after changing the proxy, body parser, signing secret, database uniqueness rule, webhook route, or order state machine. Those changes can invalidate previous evidence even when the endpoint URL remains unchanged.