Stripe webhooks

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

246 events covered 13 captured samples

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

Signature header
Stripe-Signature

Format: t=<unix seconds>,v1=<hex>

Scheme
HMAC-SHA256
Signed material
{t}.{raw body}

t from the Stripe-Signature header, a literal dot, then the JSON payload as sent.

How events are identified
type field in the body
Body format
JSON

Content type: application/json.

API versioning
api_version in the body
Replay window
5 minutes

The default tolerance in Stripe's libraries, which you can change. A tolerance of 0 disables the check.

Envelope
id, object, api_version, created, type, data, livemode, pending_webhooks, request
Agent skill
npx skills add hookdeck/webhook-skills --skill stripe-webhooks

Verify Stripe webhooks →

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

  1. Duplicate deliveries

    Stripe can send an event more than once. Deduplicate on event.id before you process it.

    Handle 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 →
  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 →
  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 →

Stripe webhook best practices

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

invoice.paid · .payment_failed · .created · .deleted +13

17 17
financial_connections

financial_connections.account.account_numbers_updated · .account.created · .account.deactivated · .account.disconnected +10

14 14
charge

charge.dispute.created · .captured · .dispute.closed · .dispute.funds_reinstated +9

13 13
customer

customer.created · .deleted · .discount.created · .discount.deleted +9

13 13
billing

billing.alert.triggered · .credit_balance_transaction.created · .credit_grant.created · .credit_grant.updated +4

8 8
payment_intent

payment_intent.succeeded · .payment_failed · .amount_capturable_updated · .canceled +4

8 8
subscription

customer.subscription.created · customer.subscription.updated · customer.subscription.deleted · customer.subscription.paused +4

8 8
climate

climate.order.canceled · .order.created · .order.delayed · .order.delivered +3

7 7
reserve

reserve.hold.created · .hold.updated · .plan.created · .plan.disabled +3

7 7
source

source.canceled · .chargeable · .failed · .mandate_notification +3

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.

Not affiliated with Stripe. Facts are compiled from public sources and linked inline.