Why Fulfil From Webhooks

Events instead of redirects

A webhook is an HTTPS POST that Stripe sends to your endpoint when something happens on your account. Each request carries an Event object with a type and the related object in data.object. Many payments finish asynchronously (bank debits, 3D Secure, delayed methods), and browsers can close before a redirect, so the reliable signal is the event: checkout.session.completed for Checkout, payment_intent.succeeded or payment_intent.payment_failed for PaymentIntents, and checkout.session.async_payment_succeeded for delayed methods used in Checkout. You register endpoints and choose which event types to receive in the Dashboard or via the API.

Let Stripe tell you what happened

Stripe sends signed event notifications to your endpoint, and your server fulfils orders from them.

Routing events by type

The core of a webhook handler.

switch (event.type) {
  case 'checkout.session.completed': {
    const session = event.data.object;
    if (session.payment_status === 'paid') await fulfilOrder(session.client_reference_id);
    // for delayed methods, wait for checkout.session.async_payment_succeeded
    break;
  }
  case 'checkout.session.async_payment_succeeded':
    await fulfilOrder(event.data.object.client_reference_id);
    break;
  case 'payment_intent.payment_failed':
    await notifyPaymentFailed(event.data.object.id);
    break;
  default:
    // ignore event types you do not handle
}

A courier's delivery confirmation

A customer saying "I paid" is like someone telling you a parcel arrived; the webhook is the courier's signed delivery receipt.

त्वरित जाँच: Why should order fulfilment happen in a webhook handler rather than on the success page?

• The customer may never reach the success page, and some payments complete later
• Webhooks are faster than redirects in every case
• Success pages cannot read query strings
• Stripe forbids success pages