Webhooks

Corvex depends on event-driven updates for anything that should not trust a redirect alone.

Billing events to treat as source of truth

• checkout.session.completed
• customer.subscription.created
• customer.subscription.updated
• invoice.paid
• invoice.payment_failed

What the handler should do

• verify the payload before processing it,
• store the event id,
• make the handler idempotent,
• and return a 2xx only after the state change is persisted.

What to document

• the event name,
• the endpoint URL,
• the retry behavior,
• the storage record that proves the event was handled,
• and the fallback path when retries fail.

Important note

Stripe webhooks should be documented separately from any internal Corvex event stream.

They are not interchangeable and should not share secrets.