302 or another 3xx
How you'll know: Your server redirected Stripe's POST: http to https, a missing trailing slash, or a www rewrite.
Fix: Stripe counts any redirect as a failure. Set the endpoint to the exact URL the redirect lands on.
A Stripe webhook is an HTTPS POST that Stripe sends to your server when something happens in your account: a payment clears, a subscription renews, a dispute opens. Setting one up takes a few minutes in Workbench. Choosing which events to listen for, and what each one should change in your other systems, is where the real decisions are.
Add it in Workbench: choose your own account, pick Thin or Snapshot payloads, tick the event types, choose Webhook endpoint and paste your public HTTPS URL.
Workbench › Webhooks › Create an event destinationCopy the signing secret: it starts whsec_ and sits on the endpoint's page behind Reveal secret. Your handler checks every request's Stripe-Signature header against it.
Answer fast: return a 2xx as soon as the signature checks out, then do the work. Slow handlers time out and Stripe marks the delivery failed.
Signature checks, duplicate events and out-of-order delivery are covered on our Stripe API page. This is the setup itself.
A snapshot event carries the whole object as it was when the event fired. A thin event carries a reference, and your code fetches the current object from the API. Stripe recommends thin for new work. Pick snapshot if a third-party tool expects the full payload, or you want previous_attributes without another call. Thin events need their own endpoint.
Subscribing to every event type sends traffic your server has to accept and ignore. Start with the short list in the table below, and add types when you add the code that handles them.
stripe listen --forward-to localhost:4242/webhook prints a temporary signing secret and forwards events to your local route. In a second terminal, stripe trigger payment_intent.succeeded fires one.
Watch for: the CLI's secret is not the one on your Workbench endpoint. Swap it when you deploy.
Live endpoints need HTTPS with TLS 1.2 or higher. Use the exact final URL, because Stripe treats any redirect as a failed delivery. An account can hold up to 16 event destinations.
Each event shows Delivered, Pending or Failed, with the status code your server returned and when the next retry is due.
The obvious event name is often not the safest trigger.
checkout.session.completed, plus checkout.session.async_payment_succeeded With bank debits and other delayed methods, the session completes before the money clears. Check payment_status, and ship on the async event when it's still unpaid.customer.subscription.updated and customer.subscription.deleted Read the subscription's status on every update rather than guessing from the event name. Past-due and paused arrive as updates. A subscription that has fully ended arrives as deleted.invoice.paid It also fires when an invoice is marked paid outside Stripe, which invoice.payment_succeeded misses.invoice.payment_failed Stripe Billing can already retry the card and email the customer. Your handler's job is the internal side: the account manager, the CRM record, the support queue.charge.dispute.created Stripe emails you about disputes too. The event is for putting the deadline and the order in your own task list. Our Stripe disputes page covers the evidence.charge.refunded and payout.paid A payout is a lump sum. Matching it to the charges and fees inside it takes a balance transaction lookup, as our QuickBooks Stripe integration guide explains.The status code next to each failed attempt usually points straight at the cause.
How you'll know: Your server redirected Stripe's POST: http to https, a missing trailing slash, or a www rewrite.
Fix: Stripe counts any redirect as a failure. Set the endpoint to the exact URL the redirect lands on.
How you'll know: Rails, Django or a similar framework rejects the POST because it has no CSRF token.
Fix: Exempt the webhook route from CSRF protection. The signature check is what protects that route.
How you'll know: The handler writes to the database, calls another API and sends an email before it responds.
Fix: Verify the signature, put the event on a queue, return 200, and do the work from the queue. Stripe recommends this for spikes too, like the first of the month when renewals bunch up.
How you'll know: Stripe couldn't make a secure connection to your server.
Fix: Usually a missing intermediate certificate or an old TLS version. Run an SSL server test against the hostname and fix what it reports.
How you'll know: The handler works now, but last night's events never got processed.
Fix: In live mode Stripe keeps retrying for up to three days, a sandbox only three times over a few hours. Past that, use Resend on an event in the Dashboard (up to 15 days) or stripe events resend in the CLI (up to 30 days).
Once deliveries show Delivered, Stripe's side is finished. The events now have to change something: an order marked shipped, a seat switched off, a refund posted to the right customer in the books, a dispute deadline on someone's list. That routing is business logic, and it's different for every company.
This is the part n-frames builds. We take each Stripe event your business cares about and connect it to the system that should act on it, whether that's QuickBooks, NetSuite, HubSpot or your own app, with a log you can check when somebody asks why an order didn't update.
Stripe for payments, access managed by hand.
A successful Stripe charge grants access, sends the note and adds the student to their cohort within moments. Support stopped fielding where's-my-access emails.
An HTTPS request Stripe sends to a URL you register whenever a chosen event happens in your account, such as a charge, a refund or a subscription change. Your code reacts to it instead of polling the API to see what changed.
Plenty of setups receive the event, log it, and stop. The value is in what happens next: the order updated, the CRM record changed, the entry posted to the books, the right person told. n-frames builds that downstream part and keeps it running as your Stripe products change.
Yes. Every request is checked against the endpoint's whsec_ signing secret before anything acts on it, inside the default five-minute timestamp window, so a forged or replayed request does nothing. Stripe also publishes the IP addresses its webhooks come from, which you can allowlist as a second layer. Signing secrets can be rolled from the endpoint's menu, with the old one kept valid for up to seven days.
Yes. The quote covers which events to handle, which systems each one updates, and what the build costs. Nothing is owed if you decide to build the Stripe webhook setup yourself.
Stripe recommends thin events for new integrations: the payload is small and your code fetches the latest object. Snapshot events suit tools that expect the full object in the payload, or code that needs previous_attributes without an extra API call. The two need separate endpoints.
Open the event in the Dashboard and click Resend, which works for up to 15 days after the event. With the Stripe CLI, stripe events resend <event_id> --webhook-endpoint=<endpoint_id> works for up to 30 days. A manual resend doesn't cancel Stripe's own scheduled retries.
Yes. Run stripe listen --forward-to with your local route and the CLI forwards events to it, giving you a temporary signing secret. A tunnel tool such as ngrok also works if you want to register a real endpoint pointing at your machine.