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.idfor idempotency - Verify signatures: Always validate webhook signatures