What we do
Tools
Industries
Department
How we workLet's talk →
Home/Stripe Webhook Setup
Stripe webhooks

Stripe Webhook Setup: The Endpoint, the Signing Secret, and Which Events to Handle

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.

Create the endpoint

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 destination

Copy 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.

From an empty endpoint to live events

Signature checks, duplicate events and out-of-order delivery are covered on our Stripe API page. This is the setup itself.

  1. 1

    Decide Thin or Snapshot

    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.

  2. 2

    Tick only the events you handle

    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.

  3. 3

    Test on your laptop with the Stripe CLI

    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.

  4. 4

    Register the public URL

    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.

  5. 5

    Watch the first deliveries

    Workbench Webhooks your endpoint Event deliveries

    Each event shows Delivered, Pending or Failed, with the status code your server returned and when the next retry is due.

Which Stripe event to build each job on

The obvious event name is often not the safest trigger.

The job Listen for Why that one
Fulfil a Checkout order 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.
Keep subscription access in step 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.
Record a paid renewal invoice.paid It also fires when an invoice is marked paid outside Stripe, which invoice.payment_succeeded misses.
Flag a failed renewal inside your team 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.
Get a dispute in front of whoever answers it 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.
Book refunds and payouts 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.

When the Event deliveries tab says Failed

The status code next to each failed attempt usually points straight at the cause.

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.

403 from a web framework

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.

Timed out

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.

TLS error

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.

Fixed the bug, events still missing

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).

What a working webhook still leaves undone

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.

What this looks like in practice

Online Course Provider

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.

Questions people ask

What is a Stripe webhook?

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.

We already receive Stripe webhooks. Why would we need this?

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.

Do you handle webhook security?

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.

Is the quote for a Stripe webhook setup really free with no obligation?

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.

Should I choose thin or snapshot events for my Stripe webhook?

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.

How do I resend a Stripe webhook event that failed?

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.

Can I test a Stripe webhook without a public URL?

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.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.