Webhooks

Webhooks are the reliable way to deliver payment results to your backend. What the user sees on screen or after a redirect is not enough on its own.

Details: Webhook Delivery and Security.

Principle

• Redirect / success page: informational
• Webhook + payments.get when needed: final state

Handler skeleton

export async function handleWebhook(rawBody: string, signature: string) {
  // 1) Verify signature
  // 2) Parse event
  // 3) Already processed with event.id?
  // 4) Update order / subscription state
  // 5) 2xx
}

Common event types

• payment.succeeded
• payment.authorized
• payment.requires_action
• payment.requires_payment_method
• payment.canceled / payment.refunded
• charge.declined (operational detail)
• checkout_session.completed (hosted checkout)

Do not rely on generic names like payment.updated; clarify the event list you subscribe to in the dashboard.

Resilience

• 401/403 on invalid signature
• No-op when the same event arrives again (idempotent)
• Queuing the handler helps at peak traffic; business logic must stay idempotent