Event	Meaning	Action Required
`payment_intent.succeeded`	Payment successful	Fulfill order, send receipt
`payment_intent.payment_failed`	Payment failed	Notify customer, retry logic
`charge.succeeded`	Charge completed	Update records
`charge.failed`	Charge failed	Handle failure
`charge.refunded`	Refund processed	Update balance, notify
`charge.dispute.created`	Chargeback initiated	Gather evidence

Subscription Events

Event	Meaning	Action Required
`customer.subscription.created`	New subscription	Provision access
`customer.subscription.updated`	Plan changed	Update access level
`customer.subscription.deleted`	Subscription canceled	Revoke access
`customer.subscription.trial_will_end`	Trial ending soon	Send reminder
`customer.subscription.paused`	Subscription paused	Suspend access

Invoice Events

Event	Meaning	Action Required
`invoice.created`	Invoice generated	Opportunity to add items
`invoice.finalized`	Invoice finalized	Ready to charge
`invoice.paid`	Invoice paid	Fulfill, send receipt
`invoice.payment_failed`	Payment failed	Start dunning
`invoice.upcoming`	Invoice coming	Preview, notify

Customer Events

Event	Meaning	Action Required
`customer.created`	New customer	Initialize profile
`customer.updated`	Customer details changed	Sync data
`customer.deleted`	Customer removed	Cleanup
`customer.source.expiring`	Card expiring	Notify to update

Webhook Analysis Output

When analyzing a webhook, provide:

## Webhook Analysis

**Event Type:** `[event.type]`
**Event ID:** `evt_[id]`
**API Version:** `[version]`
**Created:** [timestamp]

### Plain English Explanation

[Clear, non-technical explanation of what happened]

### Customer Impact

- **Customer ID:** `cus_[id]`
- **Customer Email:** [email if available]
- **Impact:** [What this means for the customer]

### Recommended Actions

1. **Immediate:** [What to do now]
2. **Follow-up:** [What to do next]
3. **Optional:** [Nice-to-have actions]

### Code Pattern

```typescript
// Suggested handler pattern
case '[event.type]':
  const [object] = event.data.object;
  // [Implementation guidance]
  break;

Related Events

Expect these events to follow:

[related.event.1] - [reason]
[related.event.2] - [reason]

Documentation

Stripe Docs: [link]


## Common Webhook Scenarios

### Successful Payment Flow

payment_intent.created
payment_intent.succeeded
charge.succeeded
invoice.paid (if subscription)


### Failed Payment Flow

payment_intent.created
payment_intent.payment_failed
charge.failed
invoice.payment_failed (if subscription) → Dunning sequence begins


### Subscription Lifecycle

customer.subscription.created
invoice.created
invoice.finalized
invoice.paid
(monthly cycle repeats 3-4)
customer.subscription.updated (if plan change)
customer.subscription.deleted (if canceled)


## Webhook Security

### Signature Verification

Always verify webhook signatures:

```typescript
const sig = request.headers['stripe-signature'];
let event;

try {
  event = stripe.webhooks.constructEvent(
    request.body,
    sig,
    process.env.STRIPE_WEBHOOK_SECRET
  );
} catch (err) {
  return response.status(400).send(`Webhook Error: ${err.message}`);
}

Idempotency

Handle duplicate webhooks:

// Check if already processed
const processed = await db.webhookEvents.findUnique({
  where: { stripeEventId: event.id }
});

if (processed) {
  return response.status(200).json({ received: true });
}

// Process and record
await processEvent(event);
await db.webhookEvents.create({
  data: { stripeEventId: event.id, processedAt: new Date() }
});

Event Object Reference

Payment Intent

{
  "id": "pi_xxx",
  "amount": 2000,
  "currency": "usd",
  "status": "succeeded",
  "customer": "cus_xxx",
  "payment_method": "pm_xxx",
  "metadata": {}
}

Subscription

{
  "id": "sub_xxx",
  "customer": "cus_xxx",
  "status": "active",
  "current_period_start": 1234567890,
  "current_period_end": 1234567890,
  "items": {
    "data": [{
      "price": {
        "id": "price_xxx",
        "unit_amount": 999
      }
    }]
  }
}

Invoice

{
  "id": "in_xxx",
  "customer": "cus_xxx",
  "subscription": "sub_xxx",
  "amount_due": 999,
  "amount_paid": 999,
  "status": "paid"
}

Testing Webhooks

Using Stripe CLI

# Listen to webhooks locally
stripe listen --forward-to localhost:3000/webhook

# Trigger specific event
stripe trigger payment_intent.succeeded

# Trigger with custom data
stripe trigger customer.subscription.created \
  --override subscription:items[0][price]=price_xxx

Test Event Patterns

# Simulate successful payment
stripe trigger invoice.paid

# Simulate failed payment
stripe trigger invoice.payment_failed

# Simulate subscription lifecycle
stripe trigger customer.subscription.trial_will_end

Quick Reference

Event Priority

Priority	Events	Response Time
Critical	payment_failed, dispute.created	Immediate
High	subscription.deleted, trial_will_end	< 1 hour
Medium	subscription.updated, invoice.paid	< 24 hours
Low	customer.updated	Batch process

Status Mapping

Stripe Status	App Status
`active`	Full access
`trialing`	Trial access
`past_due`	Grace period
`canceled`	No access
`unpaid`	Suspended

Integration with Other Skills

Use subscription-lifecycle for detailed subscription handling
Use dunning-sequences for failed payment recovery
Use revenue-recognition to update MRR metrics

stripe-webhooks

Stripe Webhook Analysis

Configuration

Webhook Event Types

Payment Events