Mapping Stripe webhooks to analytics events

If you're tracking revenue events in a SaaS that uses Stripe, you'll discover quickly that Stripe's webhook events don't map cleanly to the analytics events you want to track. This chapter covers the mapping — what Stripe webhook to listen for, what conditions to check, and what analytics event to fire. The mapping is tool-agnostic; the same logic applies whether you're sending events to Amplitude, PostHog, or anything else.

The example here uses a straightforward SaaS configuration:

• Single plan at a fixed monthly price
• 3-day free trial, no payment method required upfront
• Subscription becomes active after the trial converts (first successful charge)
• Users can cancel and resume freely; cancellation is scheduled for end of period
• No grace period — subscription expires immediately when canceled or when payment fails terminally

Your setup may differ. Where it differs, you'll need to adjust the conditions. The webhooks themselves are the same; what changes is what each webhook means in your specific context.

#The core problem

Stripe's webhooks are designed for billing operations, not analytics. They tell you what changed in Stripe's system, not what meaningful analytics event occurred.

This creates several specific challenges.

One user action triggers multiple webhooks. A single "renew my subscription" cycle fires invoice.created, payment_intent.created, charge.succeeded, invoice.paid, and customer.subscription.updated. You need to pick the right one to track.

One webhook means many things. customer.subscription.updated fires for cancellations, plan changes, payment method updates, trial extensions, metadata edits, and dozens of other state changes. You can't just listen for it — you have to inspect what changed.

Status doesn't equal payment. When a trial ends, Stripe transitions the subscription from trialing to active and then creates the invoice. If you fire "Subscription started" on the status change, you'll track conversions that haven't actually paid yet.

Configuration changes the picture. Trial periods, proration behavior, grace periods, retry schedules — all of these affect which webhooks fire and when. There's no universal mapping.

#The mapping

After working through this carefully, three webhooks cover the events you need to track.

The rest of this chapter explains how to distinguish each event within its webhook.

#Payment events: invoice.paid

invoice.paid is the only reliable signal that money actually changed hands (including the €0 invoice that opens a trial). It fires four times in the lifecycle of a paying customer:

1. When the trial subscription is created (€0 invoice, marks the trial start)
2. When the trial converts (first non-zero invoice)
3. When the subscription renews (every subsequent monthly invoice)
4. For a direct paid subscription with no trial (the first invoice)

You distinguish them using two fields: invoice.billing_reason and the relationship between invoice.period_end and subscription.trial_end.

const hadTrial = subscription.trial_end !== null;
const isCreate = invoice.billing_reason === "subscription_create";
const isCycle = invoice.billing_reason === "subscription_cycle";
const isConversionFromTrial = invoice.period_end === subscription.trial_end;

subscription.trial_end is populated when the subscription was created with a trial period. It stays on the subscription permanently — even after conversion or cancellation. So trial_end !== null reliably separates trial-based flows from direct purchases, regardless of when the webhook fires.

invoice.period_end is the end of the billing period this invoice covers. For a trial-converted invoice, period_end lands exactly on trial_end because the first paid period begins immediately after the trial. For any subsequent renewal, the period has rolled forward and the two timestamps no longer match.

#Why not check invoice.amount_paid === 0?

You might think a trial invoice is identifiable by its zero amount. It is — until you ever use a 100% discount or credit. A fully discounted real subscription would look identical to a trial start. The billing_reason + trial_end approach holds regardless.

#The mapping for invoice.paid

#Cancel and resume: customer.subscription.updated

customer.subscription.updated fires for any state change on the subscription. To detect cancellations and resumes specifically, you look at the previous_attributes field — Stripe includes only the keys that changed.

When the user cancels, Stripe sets cancel_at to the timestamp when the subscription will end (typically end of current period). When the user resumes, Stripe clears cancel_at back to null.

const wasCanceled = previous.cancel_at === null && subscription.cancel_at !== null;
const wasResumed = previous.cancel_at !== null && subscription.cancel_at === null;
const isTrial = subscription.status === "trialing";

cancel_at is a scheduled cancellation — the subscription stays active until that timestamp, then terminates. This is different from immediate cancellation, which would delete the subscription right away and fire customer.subscription.deleted instead. Most SaaS apps use scheduled cancellation so users keep access through the end of their billing period.

To tell whether the action was on a trial or an active paid subscription, check subscription.status. A trial-in-progress subscription has status trialing; an active paid one has status active.

#The mapping for customer.subscription.updated

customer.subscription.updated fires for many other reasons (plan changes, payment method updates, etc.) — none of those match the conditions above, so they don't produce analytics events from this handler.

#Expiration: customer.subscription.deleted

When a subscription actually terminates, customer.subscription.deleted fires. This happens when a scheduled cancellation date arrives, when payment retries are exhausted, or when a trial ends without converting.

The webhook gives you the subscription's final state. It does not include previous_attributes — the subscription is gone, and Stripe just hands you what was true at termination. So you have to infer the type of expiration from what remains.

The trick: current_period_end moves forward with each billing cycle. If a trial expires without converting, the subscription never had a paid billing cycle, so current_period_end still equals the original trial boundary (which equals trial_end). If the subscription paid at least one cycle, the two values diverged.

const wasTrialExpiration = trial_end !== null && current_period_end === trial_end;

#The mapping for customer.subscription.deleted

A subscription with no trial that's deleted (direct paid sub that expired) falls into the second bucket — its trial_end is null, so the first condition is false.

#The complete mapping table

#Testing

These conditions need to be verified against your specific Stripe configuration. The way to do this:

1. Enable Stripe test mode
2. Walk through each subscription flow manually using test cards
3. Log the raw webhook payloads — every field, not just the ones you're using
4. Use Stripe's test clocks to fast-forward time and trigger trial conversions, renewals, and expirations in seconds

The conditions above work for the setup described at the top of this chapter. If your trial length is different, your billing interval is different, or you use proration or grace periods, some conditions will need adjustment. The webhook payloads tell you exactly what changed; you just have to look.

#What's not covered

This mapping handles the lifecycle for a single-plan, single-currency, trial-then-paid SaaS. It doesn't handle:

• Plan upgrades and downgrades — these fire customer.subscription.updated with previous.plan set. You'd add a condition checking previous.plan to detect them.
• Payment failures and retries — Stripe fires invoice.payment_failed. If you want to track failed payments as analytics events, that's the webhook.
• Refunds — charge.refunded. If refunds are meaningful in your analytics, track them.
• Multi-currency or proration — both work with the conditions above, but require extra properties on the events to interpret correctly.

Add these to your mapping as needed for your business.

#Where the tool-specific code lives

This chapter covers what event to fire and when — but not how to actually send it to your analytics tool. That's tool-specific. For Amplitude, see Stripe revenue tracking. The same conditions translate directly to PostHog or Mixpanel; only the SDK calls change.