Webhooks

Fired when a user completes Stripe Checkout for a paid plan. Use to activate the subscription in your dashboard.

{
  "type": "checkout.session.completed",
  "data": { "object": {
    "id": "cs_test_abc",
    "customer": "cus_test_123",
    "subscription": "sub_test_456",
    "metadata": { "org_id": "org_01HXYZ" }
  } }
}

New subscription created (after checkout or via API). Use to load the plan into context.

{
  "type": "customer.subscription.created",
  "data": { "object": {
    "id": "sub_test_456",
    "status": "active",
    "items": { "data": [{ "price": { "id": "price_pro_monthly" } }] }
  } }
}

Plan change, upgrade, downgrade or billing cycle shift. Reconcile with your internal state.

{
  "type": "customer.subscription.updated",
  "data": { "object": {
    "id": "sub_test_456",
    "status": "active",
    "cancel_at_period_end": true
  } }
}

Subscription ended at period close. API keys keep working through the period, then fall back to Free.

{
  "type": "customer.subscription.deleted",
  "data": { "object": { "id": "sub_test_456", "status": "canceled" } }
}

Successful invoice payment. Send the customer a payment confirmation.

{
  "type": "invoice.paid",
  "data": { "object": {
    "id": "in_test_789",
    "amount_paid": 4900,
    "currency": "eur",
    "hosted_invoice_url": "https://invoice.stripe.com/..."
  } }
}

Payment failed. Trigger dunning and notify the customer.

{
  "type": "invoice.payment_failed",
  "data": { "object": {
    "id": "in_test_789",
    "attempt_count": 1,
    "next_payment_attempt": 1717804800
  } }
}

Billing address, email or tax id changed. Sync to the org profile.

{
  "type": "customer.updated",
  "data": { "object": {
    "id": "cus_test_123",
    "email": "billing@example.ro",
    "address": { "country": "RO" }
  } }
}