Skip to main content

Event Structure

All webhook events follow this structure:

Subscription Events

subscription.created

New subscription started.

subscription.renewed

Billing period advanced after a successful renewal.

subscription.canceled

Subscription canceled (may remain active until period end).

Payment Events

payment.succeeded

payment.failed

Payment attempt failed.

Invoice Events

invoice.created

New invoice generated.

invoice.paid

Invoice paid in full.

invoice.payment_failed

Payment attempt on invoice failed.

Customer Events

customer.created

New customer added.

customer.updated

Customer details changed.

Best Practices

  • Respond quickly: Return 200 within 5 seconds
  • Process async: Queue events for background processing
  • Handle duplicates: Use event.id for idempotency
  • Verify signatures: Always validate webhook signatures