Stripe webhooks
Stripe webhooks are HTTP callbacks that notify your server in real time about events in your Stripe account.
How Stripe webhooks work
Webhooks push events to your server as they happen, so you don't have to poll the Stripe API for changes. When a customer completes a payment, disputes a charge or updates a subscription, or when a billing cycle completes, Stripe sends an HTTPS POST with a JSON Event object to each endpoint subscribed to that event type.
The event's type field says what happened, such as invoice.paid. In a snapshot event, data.object holds the API object it happened to, in the API version your account was set to when the event occurred. Thin events carry a reference to the object instead, which you fetch from the API.
Key facts
{t}.{raw body} t from the Stripe-Signature header, a literal dot, then the JSON payload as sent.
5 minutes The default tolerance in Stripe's libraries, which you can change. A tolerance of 0 disables the check.
id, object, api_version, created, type, data, livemode, pending_webhooks, request Setting up Stripe webhooks
- Create an endpoint in the Webhooks tab in Workbench or with the Event Destinations API, then choose its payload format and event types.
- Stripe can also send events straight to Amazon EventBridge or Azure Event Grid, with no HTTP endpoint to run.
- Test locally with the Stripe CLI:
stripe listen --forward-to localhost:4242/webhookforwards events to your machine, andstripe triggersends test events. - Resend an event from the Dashboard for up to 15 days after it was created, or with
stripe events resendfor up to 30 days.
Delivery behaviour
a few seconds Stripe doesn't publish the exact value Retries up to 3 days exponential backoff in live mode; three attempts over a few hours in test mode Endpoint disabled after 3 days of continuous failures in live mode; Stripe sends a notification Ordering not guaranteed events are sent concurrently, so a later one can arrive first Known failure modes
From Hookdeck's Stripe guide →-
Duplicate deliveries
Stripe can send an event more than once. Deduplicate on
Handle duplicates →event.idbefore you process it. -
Out-of-order delivery
Stripe doesn't guarantee delivery order, and
Handle ordering →createdis only accurate to the second. Fetch the object's current state from the API when order matters. -
Endpoint disabled after an outage
In live mode Stripe retries for up to three days, then disables an endpoint that keeps failing. Keep it available, and reconcile from the Events API after an outage.
Retries and disabled endpoints → -
Invoice events arrive up to an hour late
Stripe waits until an hour after the last successful webhook before sending invoice events. Don't rely on them for time-sensitive work.
Other Stripe limits →
Stripe webhook best practices
- Verify every signature. Without it, anyone can send fake events to your endpoint and trigger actions like fulfilling orders.
- Return a 2xx quickly. Respond before any complex logic, so a slow handler doesn't time out and get retried.
- Process events asynchronously. Push events to a queue and work through them outside the request, which also absorbs spikes such as a billing run.
- Subscribe only to events you process. Listening for every event type adds load on your server and gives you nothing in return.
- Separate test and live endpoints. Use different URLs and signing secrets, so test events can't touch production data.
- Reconcile regularly. Check Stripe's API on a schedule to catch events you missed during downtime or because of a bug.
Common Stripe webhook events
Payments
payment_intent.succeeded | Payment completes successfully |
payment_intent.payment_failed | Payment attempt fails |
charge.refunded | Charge refunded, in full or in part |
charge.dispute.created | Customer disputes a charge |
checkout.session.completed | Checkout Session completes |
Subscriptions
customer.subscription.created | New subscription starts |
customer.subscription.updated | Subscription changes (plan, quantity) |
customer.subscription.deleted | Subscription canceled or expired |
Invoices
invoice.paid | Invoice payment succeeds |
invoice.payment_failed | Invoice payment fails |
invoice.finalized | Draft invoice finalized and now open |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
invoice | 17 | 17 |
financial_connections | 14 | 14 |
charge | 13 | 13 |
customer | 13 | 13 |
billing | 8 | 8 |
payment_intent | 8 | 8 |
subscription | 8 | 8 |
climate | 7 | 7 |
reserve | 7 | 7 |
source | 7 | 7 |
29 more resources, including Other Stripe events. All 246 events →
In this hub
| Webhook events → | Every covered Stripe event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to Stripe events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill stripe-webhooks |
Keep an outage from disabling your Stripe endpoint.
Hookdeck Event Gateway accepts every Stripe delivery, verifies its signature, queues events and retries to your service on your schedule.