# Stripe webhooks

Stripe webhooks are HTTP callbacks that notify your server in real time about events in your Stripe account.

Agent skill: `npx skills add hookdeck/webhook-skills --skill stripe-webhooks` ([details](https://hookdeck.com/webhooks/stripe/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Stripe's official docs](https://docs.stripe.com/event-destinations).

[Overview](https://hookdeck.com/webhooks/stripe) · [Webhook events (246)](https://hookdeck.com/webhooks/stripe/events) · [MCP events](https://hookdeck.com/webhooks/stripe/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/stripe/verify) · [Production guide](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/stripe/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `Stripe-Signature` Format: t=<unix seconds>,v1=<hex> | [Stripe docs](https://docs.stripe.com/webhooks) |
| Scheme | `HMAC-SHA256` | [Stripe docs](https://docs.stripe.com/webhooks) |
| Signed material | `{t}.{raw body}` t from the Stripe-Signature header, a literal dot, then the JSON payload as sent. | [Stripe docs](https://docs.stripe.com/webhooks) |
| How events are identified | `type field in the body` | [Stripe docs](https://docs.stripe.com/event-destinations) |
| Body format | `JSON` Content type: application/json. | [Stripe docs](https://docs.stripe.com/webhooks) |
| API versioning | `api_version in the body` | [Stripe docs](https://docs.stripe.com/webhooks) |
| Replay window | `5 minutes` The default tolerance in Stripe's libraries, which you can change. A tolerance of 0 disables the check. | [Stripe docs](https://docs.stripe.com/webhooks) |
| Envelope | `id, object, api_version, created, type, data, livemode, pending_webhooks, request` | [Stripe docs](https://docs.stripe.com/event-destinations) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill stripe-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/stripe/skill) |

[Verify Stripe webhooks](https://hookdeck.com/webhooks/stripe/verify)

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

## 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/webhook` forwards events to your machine, and `stripe trigger` sends test events.
- Resend an event from the Dashboard for up to 15 days after it was created, or with `stripe events resend` for up to 30 days.

## Delivery behaviour

- **Timeout:** a few seconds. Stripe doesn't publish the exact value. [Guide](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** up to 3 days. exponential backoff in live mode; three attempts over a few hours in test mode. [Guide](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts#retries)
- **Endpoint disabled:** after 3 days. of continuous failures in live mode; Stripe sends a notification. [Guide](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts#retries)
- **Ordering:** not guaranteed. events are sent concurrently, so a later one can arrive first. [Guide](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts#ordering)

## Known failure modes

1. **Duplicate deliveries.** Stripe can send an event more than once. Deduplicate on `event.id` before you process it. [Handle duplicates](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts#duplicates)
2. **Out-of-order delivery.** Stripe doesn't guarantee delivery order, and `created` is only accurate to the second. Fetch the object's current state from the API when order matters. [Handle ordering](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts#ordering)
3. **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](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts#retries)
4. **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](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts#other-limits)

From [Hookdeck's Stripe guide](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts).

## Stripe webhook best practices

- **[Verify every signature](https://hookdeck.com/webhooks/stripe/verify).** Without it, anyone can send fake events to your endpoint and trigger actions like fulfilling orders.
- **[Return a 2xx quickly](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts#timeouts).** Respond before any complex logic, so a slow handler doesn't time out and get retried.
- **[Process events asynchronously](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts#timeouts).** 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](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts#choosing-events).** Listening for every event type adds load on your server and gives you nothing in return.
- **[Separate test and live endpoints](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts#choosing-events).** Use different URLs and signing secrets, so test events can't touch production data.
- **[Reconcile regularly](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts#retries).** 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](https://hookdeck.com/webhooks/stripe/events/payment-intent#payment_intent.succeeded): Payment completes successfully
- [payment_intent.payment_failed](https://hookdeck.com/webhooks/stripe/events/payment-intent#payment_intent.payment_failed): Payment attempt fails
- [charge.refunded](https://hookdeck.com/webhooks/stripe/events/charge#charge.refunded): Charge refunded, in full or in part
- [charge.dispute.created](https://hookdeck.com/webhooks/stripe/events/charge#charge.dispute.created): Customer disputes a charge
- [checkout.session.completed](https://hookdeck.com/webhooks/stripe/events/checkout#checkout.session.completed): Checkout Session completes

### Subscriptions

- [customer.subscription.created](https://hookdeck.com/webhooks/stripe/events/subscription#customer.subscription.created): New subscription starts
- [customer.subscription.updated](https://hookdeck.com/webhooks/stripe/events/subscription#customer.subscription.updated): Subscription changes (plan, quantity)
- [customer.subscription.deleted](https://hookdeck.com/webhooks/stripe/events/subscription#customer.subscription.deleted): Subscription canceled or expired

### Invoices

- [invoice.paid](https://hookdeck.com/webhooks/stripe/events/invoice#invoice.paid): Invoice payment succeeds
- [invoice.payment_failed](https://hookdeck.com/webhooks/stripe/events/invoice#invoice.payment_failed): Invoice payment fails
- [invoice.finalized](https://hookdeck.com/webhooks/stripe/events/invoice#invoice.finalized): Draft invoice finalized and now open

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [invoice](https://hookdeck.com/webhooks/stripe/events/invoice) | 17 | 17 |
| [financial_connections](https://hookdeck.com/webhooks/stripe/events/financial-connections) | 14 | 14 |
| [charge](https://hookdeck.com/webhooks/stripe/events/charge) | 13 | 13 |
| [customer](https://hookdeck.com/webhooks/stripe/events/customer) | 13 | 13 |
| [billing](https://hookdeck.com/webhooks/stripe/events/billing) | 8 | 8 |
| [payment_intent](https://hookdeck.com/webhooks/stripe/events/payment-intent) | 8 | 8 |
| [subscription](https://hookdeck.com/webhooks/stripe/events/subscription) | 8 | 8 |
| [climate](https://hookdeck.com/webhooks/stripe/events/climate) | 7 | 7 |
| [reserve](https://hookdeck.com/webhooks/stripe/events/reserve) | 7 | 7 |
| [source](https://hookdeck.com/webhooks/stripe/events/source) | 7 | 7 |

29 more resources. [All 246 events](https://hookdeck.com/webhooks/stripe/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/stripe/events): Every covered Stripe event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/stripe/mcp-events): How an agent subscribes to Stripe events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/stripe/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/stripe/guide-duplicates-ordering-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/stripe/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill stripe-webhooks`
---

Not affiliated with Stripe. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/stripe.json) · [Report a correction](https://hookdeck.com/contact)
