Stripe event

A Stripe event is the record Stripe writes when something changes in your account. A card payment succeeds, a refund goes out, a subscription ends or a payout lands, and each one produces an Event object with an ID that starts with evt_. Webhooks deliver events to your server, and every alert, sync or report you build on Stripe starts from them.

Fields on a Stripe event

The fields you will use most:

• type says what happened, written as object then action. Examples are payment_intent.succeeded, charge.refunded, charge.dispute.created, customer.subscription.deleted and payout.paid.
• data.object is a full copy of the affected resource at the moment the event was created. A charge.refunded event carries the whole Charge, and payment_intent.succeeded carries the PaymentIntent.
• data.previous_attributes appears only on .updated events. It holds the fields that changed and their old values, which is how you tell a plan change from a card update inside customer.subscription.updated.
• created is a Unix timestamp in seconds.
• livemode is true for real money and false for test data.
• api_version is the API version used to render data. It never changes, because data never changes.
• request.id is the API request that caused the event. It is null when Stripe acted on its own, as with automatic subscription renewals.
• account appears on Connect platforms and names the connected account the event came from.
• pending_webhooks counts the endpoints that haven't acknowledged the event yet.

One action can produce several events. In Stripe's example, creating a subscription fires both customer.subscription.created and charge.succeeded.

Events are snapshots

Because data.object is a snapshot, an event can be out of date when you process it. If a charge is refunded soon after it succeeds, a charge.succeeded event you handle late still shows the charge as not refunded. Use the event to learn what happened, and fetch the object from the API when you need its current state.

Stripe doesn't guarantee that events arrive in order, and it can deliver the same event twice. Different events can share the same created second, so the timestamp can't be used for ordering or deduplication. Track event IDs instead.

How to receive Stripe events

• Webhooks. A webhook endpoint subscribed to the event types you care about receives them in real time.
• The Events API. GET /v1/events lists events and GET /v1/events/:id retrieves one. Events stay in the API for 30 days, which helps you catch up after an outage. Store anything you need for longer.

Which Stripe events to watch

Stripe defines hundreds of event types, and most are bookkeeping. For a small SaaS or ecommerce team, a few carry most of the money:

• payment_intent.payment_failed and invoice.payment_failed mean revenue at risk, often the start of involuntary churn.
• charge.dispute.created is a chargeback. Stripe takes the disputed amount plus a dispute fee, and you usually have 7 to 21 days to respond.
• charge.refunded means money is going back to a customer.
• customer.subscription.created and customer.subscription.deleted move recurring revenue up or down.
• payout.paid means a payout is expected to be in your bank account.

Who acts depends on the type. Failed payments go to whoever handles billing, disputes to the founder or finance, and cancellations to customer success. Which Stripe alerts go to finance, support, and founders has a fuller routing plan.

How ChargeBell uses Stripe events

ChargeBell reads your events through a read-only Stripe connection and turns the important ones into Slack alerts written in plain English. Each alert shows the amount and the customer. Payment alerts add what you keep after fees, and subscription alerts add the MRR change. ChargeBell deduplicates on the event ID, so a redelivered event produces one alert. Each alert type can go to its own channel, and alerts for money at risk, such as a failed payment, are critical and come through during quiet hours. The Stripe Slack integration page explains the setup.