What is a Stripe webhook?

What a webhook is

A webhook turns the usual direction of an API around. Instead of your site asking Stripe for news, Stripe calls your site. You register an endpoint, an HTTPS address on your server or function, and choose which event types to receive. When one happens, Stripe sends a POST request with a JSON event object describing it. Stripe signs each request with a secret only you and Stripe know, the endpoint's signing secret starting whsec_, and puts the signature in the Stripe-Signature header.

How a site handles one

The endpoint reads the raw request body, verifies the signature with the signing secret and rejects anything that fails, which stops anyone faking a paid order by calling the address themselves. It then reads the event type and acts: for checkout.session.completed it looks up the order by the session's id or metadata and marks it paid. It returns a 2xx status quickly, before slow work such as emails, because Stripe treats slow or failed responses as undelivered. In live mode Stripe retries failed deliveries with backoff for up to three days, so the handler must be idempotent: processing the same event twice must not ship two parcels.

When it matters

Any site that takes money online needs one. The page a customer lands on after paying is not proof of payment; the customer might close the tab first, or a delayed payment method such as a bank debit might clear days later. Subscriptions need webhooks even more, because renewals, failed payments and cancellations happen while nobody is on the site. Refunds made in the Stripe dashboard also only reach the site's order records through a webhook.

Common mistakes

Marking orders paid from the success page's URL instead of the webhook. Parsing the JSON before verifying the signature, so the raw body no longer matches and every check fails. Skipping verification altogether. Doing slow work before responding, so Stripe times out and retries. Not handling duplicates. Listening for every event type when four or five are needed. Using the test mode signing secret in live mode. And forgetting that events can arrive out of order, so a refund might be processed before the payment it refers to.

Where it shows up in OneCraft

OneCraft sites take payments through a payments broker: Stripe Checkout as a direct charge on the owner's own connected Stripe account, for one off orders, subscriptions from a plans table and the Stripe billing portal. Prices are read from the site's own database, never from the browser, and a webhook marks each order paid or refunded. Stripe is connected in account Settings, Payments. The platform fee is 2% on Starter, 1% on Pro and 0.5% on Pro+, with Stripe's fees on top, and the free plan cannot take payments.

Questions people ask