Blog · 16 November 2026 · 8 minute read
Stripe webhooks explained: what they are, how to test them, and the mistakes to avoid
A plain-English guide to payment webhooks: why your app needs them, how signature checking and retries work, and how to test the whole flow before real money.
What a webhook is
A webhook is a message a service sends to your app when something happens. With payments, the something is usually "this customer just paid". Your payment provider calls an address on your site and delivers the event, and your app reacts: it unlocks the account, sends the receipt, starts the subscription.
Without a webhook your app only knows what the browser tells it, and the browser is not reliable. People close the tab on the confirmation page. Cards are approved a few seconds late. A subscription renews at three in the morning with nobody on your site. The webhook is the only signal that covers all of these.
The flow, step by step
- A customer pays on the checkout page hosted by your payment provider.
- The provider records the payment and creates an event.
- It sends that event to the webhook address you registered, for example https://yourdomain/api/stripe/webhook.
- Your app checks the event is genuine, then acts on it.
- Your app answers with a success status. If it does not, the provider tries again later.
Always check the signature
Your webhook address is public, so anyone can send requests to it. Every real event is signed with a secret that only you and the provider know, and your code must verify that signature before trusting anything in the message. Use the provider's own library for this, and verify against the raw request body: parsing the body first changes it and the check fails.
The signing secret is separate from your API key, and it is different in test mode and live mode. Mixing them up is the most common reason a webhook that worked yesterday fails today.
Expect every event more than once
Providers retry when they do not get a quick success answer, and occasionally deliver the same event twice even when they do. If your handler grants access each time it runs, a customer could be credited twice.
The fix is to record the ID of each event you have handled and skip any you have seen before. Do this from the first version. It is a few lines, and it prevents the kind of bug that only shows up with real customers.
Answer fast, work afterwards
Acknowledge the event quickly and do slow work, such as sending email or calling other services, after you have answered or in a background job. A handler that takes too long looks like a failure to the provider, which then retries, and now you are processing the same event several times at once.
Which events to listen for
Listen only for the events you act on. For a one-off payment that is the event saying a checkout was completed. For subscriptions you also need the events for a successful renewal, a failed payment and a cancellation, so access ends when it should. Subscribing to everything makes your logs noisy and your handler slow.
Testing before real money
- Work in test mode, where no card is charged.
- Create the product, the price and the webhook endpoint against your real domain.
- Buy with a test card. The best known is 4242 4242 4242 4242, with any future date and any security code.
- Check the provider's dashboard shows the event as delivered with a success status.
- Check your app did what it should: the account is unlocked, the receipt went out.
- Test a cancellation and a failed payment too, not only the happy path.
Going live
Live mode has its own keys, its own prices and its own webhook secret. Going live means creating those again in live mode and replacing all of them in your host's environment together. Then make one real purchase yourself and refund it. Until you have seen a real payment arrive, you do not know that it works.
What Shipyard does here
A launch creates the product, prices and webhook endpoint in test mode on your real domain, writes the keys and the signing secret to your host, and sends a test event as part of its health check. When you are ready, one step creates the same set in live mode and swaps the keys over.
Launch in an hour, not a weekend
Shipyard connects your accounts once, then sets up the domain, hosting, database, email and payments for every new product.
See how it works