Industrial optical switch with connected rubber cables of different colors with stickers representing letters and numbers and plastic terminations
Photo by Brett Sayles on Pexels

Fraud Controls

Part of Checkout integrations

Testing webhooks for payment success and failure

Check payment webhook verification, durable acceptance, order updates, repeated events and recovery.

This is an editorial pen name used by the publication, not a claim of an independently verified personal identity. Original editorial credit: Desk Payment Risk.

Test payment webhooks across the full chain: provider event, authenticated delivery, durable acceptance, handler outcome and order transition. Exercise success and failure separately, then test repeated and interrupted delivery. An HTTP acknowledgement alone does not prove the order changed correctly. The examples below use Stripe Checkout.

Set the expected order result

For each case, record the store order reference, provider payment reference, event type, provider status and expected store transition. Check the customer message and fulfilment queue as well as the endpoint response.

CaseResult to inspect
Payment succeedsThe linked order reaches its permitted paid state once.
Payment failsThe order stays out of fulfilment and retains the failed attempt.
Payment is processingThe order remains pending until the required later outcome.
Delivery is repeatedThere is no second transition or fulfilment action.
Events arrive out of orderThe handler checks current state and retrieves or investigates missing context.

Map each case to a Stripe event type. checkout.session.completed occurs when a Checkout Session has been successfully completed. For a delayed payment method, checkout.session.async_payment_succeeded occurs when the payment finally succeeds and checkout.session.async_payment_failed when it fails. payment_intent.payment_failed occurs when a PaymentIntent has failed the attempt to create a payment method or a payment.

Stripe's hosted Checkout fulfilment guidance says to check payment_status before fulfilment. A completed Session is not automatically a paid order: Stripe exposes a separate payment_status field, and the release rule must fit the offered method. With a delayed method, hold the order as pending on checkout.session.completed and release it only on the async success event.

Verify and accept the delivery

Use the provider's permitted test tools. For Stripe, verify each request with the Stripe-Signature header by calling constructEvent() with the raw request body, the signature header and the endpoint secret. Test with the body string exactly as Stripe sent it, before any parsing.

The endpoint secret starts with a whsec_ prefix. For a Dashboard endpoint, open the endpoint and click Reveal secret; with the Stripe CLI, the secret is printed in the terminal when you run stripe listen. The two secrets differ, so test that an event signed with the wrong one is rejected and cannot change an order.

After verification, accept the event durably before returning a successful HTTP response. This may mean completing the small order operation or storing work reliably for a worker.

Return promptly. If the application cannot retain the event or work, do not acknowledge it as accepted. A worker failure after acknowledgement needs an internal retry or investigation path.

Check duplicates and recovery

Make the order transition safe when it is called multiple times with the same Checkout Session ID; Stripe's hosted Checkout guidance requires this. Record each processed event ID, and when an already processed event arrives, ignore it and return a successful response so Stripe stops retrying. A late event should be interpreted against the current payment and order state rather than overwriting a valid later result.

Interrupt delivery in a permitted test setup and inspect the provider's delivery record and the recovered order. If an endpoint temporarily can't process events, Stripe automatically resends undelivered events for up to three days. To recover sooner, call the List Events API with delivery_success set to false; it returns events created in the last 30 days.

Confirm the same order remains correct after the automatic retry and after a manual reprocessing run, including when both happen together.

Compare the records

For each case, compare the provider event, endpoint delivery, handler outcome and order timeline. Check amount and currency when they govern the transition. Investigate an unmatched event instead of creating an order from a loose amount match.

Stripe's testing guidance describes successful and declined sandbox payment scenarios using test cards, and its webhook guidance mentions Stripe CLI for local testing. A triggered sample event checks delivery and parsing; a complete permitted payment path with a declined test card is needed to check the actual order reference, amount and customer message on failure. Record which kind of check was run. Neither establishes production settlement timing.

Stripe Webhook Testing Key Metrics and Guidelines

Max retry duration
Up to 3 days
Endpoint secret prefix
whsec_
Required verification step
Use `constructEvent()` with raw body and signature header

Further reading: Overview (docs.bigcommerce.com).

More from Fraud Controls