A Webhook Example: Payment Completed

Build the mental model

Consider a concrete example: a customer completes a payment on your checkout page, but the actual charge is processed by a separate payment provider. The provider's server knows the instant the charge succeeds; your server does not.

The webhook model solves this cleanly: the payment provider watches for the event, and the moment it completes, it sends an HTTP POST to a URL you registered in advance, carrying the payment details in the body.

Customer pays

The customer completes checkout on your site; the actual charge is processed by the payment provider.

Provider detects completion

The payment provider's own systems confirm the charge succeeded — your server has no visibility into this step.

Provider sends the webhook

The provider sends an HTTP POST to your registered URL, carrying the payment details in the body.

Your server updates the order

Your handler reads the payload and marks the order as paid in your database — no polling required.

Compare this to polling, where your server repeatedly sends requests asking if it's done. Polling wastes requests before the event happens and still adds a delay of up to one polling interval afterward.

This is the core reason payment providers, chat platforms, and CI systems favor webhooks for events like this. The tradeoff is that receiving a webhook makes you responsible for verifying it and handling delivery correctly.

text

PAYMENT WEBHOOK SEQUENCE
------------------------
-----
1. Customer pays on your checkout page
        |
        v
2. Payment Provider detects the charge completed
        |
        v
3. Payment Provider sends POST /webhook to Your Server
        |
        v
4. Your Server updates order status to "paid" in the DB

Connect it to a real scenario

The code below models the four-step sequence: a webhook payload arrives claiming a payment completed, and your handler decides what to do with it, pulling out the order ID and amount and returning the exact status update.

Notice the function does not fetch anything or ask anyone whether the payment happened — it trusts the payload and reacts to it. That's the whole efficiency gain: no outbound request from your side at all.

Also notice the function checks event.type before doing anything else — bailing out safely with a clear reason string, rather than assuming every payload is a completed payment, is a habit worth building immediately.

A webhook lets the payment provider tell your server the instant a payment completes, instead of your server asking repeatedly.
Polling wastes requests before the event happens and still adds a delay of up to one polling interval afterward.
Your webhook handler should check the event type before trusting a payload — not every request is a completed payment.

Try the working example

javascript

function handlePaymentWebhook(payload) {
  const event = JSON.parse(payload);
  if (event.type !== "payment.completed") {
    return { updated: false, reason: `Unhandled event type: ${event.type}` };
  }
  const { orderId, amount, currency } = event.data;
  return {
    updated: true,
    orderId,
    newStatus: "paid",
    message: `Order ${orderId} marked as paid (${amount} ${currency}) via webhook`
  };
}

const incoming = JSON.stringify({
  type: "payment.completed",
  data: { orderId: "ord_482", amount: 4200, currency: "USD" }
});

console.log(handlePaymentWebhook(incoming));

You should see

{
  updated: true,
  orderId: 'ord_482',
  newStatus: 'paid',
  message: 'Order ord_482 marked as paid (4200 USD) via webhook'
}

5-minute try-it

Extend handlePaymentWebhook to also handle a 'payment.refunded' event type, returning a status update that marks the order as refunded.

One important caution

Assuming the webhook payload always represents the event type you expect, without checking event.type first.

Treating a webhook as a guarantee the payment truly succeeded on the customer's end without any other verification, such as signature checking covered next.

Stripe Docs — Webhooks overview — API Integration & Webhooks