WebhookWhat is webhook?An HTTP request that a service sends to your server when a specific event occurs, like a payment completing. Your server processes the event automatically. Ask AI for more vs APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. Ask AI for more pollingWhat is polling?Repeatedly asking a server at regular intervals if anything has changed, which works but wastes resources when nothing is new. Ask AI for more

There are two ways to learn about events in another system: you can ask repeatedly (polling) or you can be told when something happens (webhooks). The difference matters for cost, latencyWhat is latency?The time delay between sending a request and receiving the first byte of the response, usually measured in milliseconds. Ask AI for more, and reliability.

Polling (the naive approach):

// Your server asks Stripe every minute: "Any new orders?"
setInterval(async () => {
  const orders = await fetch('https://api.stripe.com/v1/orders?status=new');
  for (const order of orders.data) {
    await processOrder(order);
  }
}, 60000);

Problems with polling: up to 60 seconds of latency, unnecessary API calls when nothing changed, you burn through rate limits, and you pay for compute to run the polling loop 24/7.

Webhook (the event-driven approach):

// Stripe calls YOUR URL the instant an order is created
app.post('/webhooks/stripe', (req, res) => {
  const event = req.body;
  // Process immediately - no delay, no wasted calls
  handleEvent(event);
  res.status(200).send('OK');
});

The trade-off is clear: webhooks are cheaper and faster, but they require you to handle security (signature verification), reliability (idempotency), and infrastructure (a publicly accessible endpointWhat is endpoint?A specific URL path on a server that handles a particular type of request, like GET /api/users. Ask AI for more).

WebhookWhat is webhook?An HTTP request that a service sends to your server when a specific event occurs, like a payment completing. Your server processes the event automatically. Ask AI for more lifecycle

Here is what happens when an event triggers a webhook:

1. Event occurs at Stripe (e.g., payment succeeds)
2. Stripe creates an event object with a unique ID
3. Stripe POSTs the event to your registered URL
4. Your server receives the request
5. You verify the signature
6. You respond 200 (acknowledgment)
7. You process the event asynchronously

The critical insight is that steps 5-6 should happen in milliseconds. Step 7 (the actual business logic) can take as long as it needs because you have already acknowledged receipt.

What can go wrong

Each of these scenarios happens in production. Not "might happen", happens. If you handle 1,000 webhooks per day, you will see retries within the first week. If you handle 10,000 per day, you will see every failure mode on this list within a month.

WebhookWhat is webhook?An HTTP request that a service sends to your server when a specific event occurs, like a payment completing. Your server processes the event automatically. Ask AI for more signature

Why verify? Your webhook URL is just a public HTTPWhat is http?The protocol browsers and servers use to exchange web pages, API data, and other resources, defining how requests and responses are formatted. Ask AI for more endpointWhat is endpoint?A specific URL path on a server that handles a particular type of request, like GET /api/users. Ask AI for more. Anyone on the internet can POST to it. How do you know the request actually came from Stripe and not from an attacker?

How signatures work:

1. You and Stripe share a secret key (the webhook signing secret)
2. When Stripe sends a webhook, it computes an HMACWhat is hmac?A keyed hash function that produces a fixed-length digest from a message and a secret key - used in webhook signatures and JWT signing. Ask AI for more-SHA256 of the payloadWhat is payload?The data sent in the body of an HTTP request, such as the JSON object you include when creating a resource through a POST request. Ask AI for more using that secret
3. Stripe includes the signature in the Stripe-Signature header
4. You recompute the HMAC on your side and compare, if they match, the request is genuine

const stripe = require('stripe')(process.env.STRIPE_SECRET);

app.post('/webhooks/stripe', (req, res) => {
  const sig = req.headers['stripe-signature'];
  const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;

  let event;
  try {
    // Signature verification - this is the critical line
    event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
  } catch (err) {
    console.log(`Webhook signature verification failed.`);
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // If we reach here, the event is authentic
  handleEvent(event);
  res.status(200).json({ received: true });
});

Different providers use different signature schemes. Stripe uses HMAC-SHA256 in a custom header. GitHub uses HMAC-SHA256 in X-Hub-Signature-256. Twilio uses a different algorithm entirely. Always check the providerWhat is provider?A wrapper component that makes data available to all components nested inside it without passing props manually. Ask AI for more's documentation for the exact verification method.

Idempotency: the key concept

Problem: The same webhookWhat is webhook?An HTTP request that a service sends to your server when a specific event occurs, like a payment completing. Your server processes the event automatically. Ask AI for more can arrive multiple times. This happens because of retries after timeouts, network duplicates, or sender bugs. If your handler creates an order on every call, duplicate webhooks create duplicate orders.

Solution: Use the event's unique ID as an idempotency keyWhat is idempotency key?A unique client-generated string sent with a mutation request so the server can safely deduplicate retried requests. Ask AI for more. Before processing, check if you have already handled this event. If yes, skip it and return 200.

app.post('/webhooks/stripe', async (req, res) => {
  const eventId = req.body.id;  // Unique Stripe event ID (evt_...)

  // Check if already processed
  if (await isEventProcessed(eventId)) {
    console.log(`Event ${eventId} already processed, skipping`);
    return res.status(200).send('Already processed');
  }

  try {
    await processPayment(req.body);
    // Mark as processed (with TTL for cleanup)
    await markEventProcessed(eventId, { ttl: '7d' });
    res.status(200).send('OK');
  } catch (error) {
    // Do NOT mark as processed - let the sender retry
    console.error('Processing failed:', error);
    res.status(500).send('Error');
  }
});

The key detail is what happens on error: you return 500 without marking the event as processed. This tells the sender to retry, and the next attempt will find the event unprocessed and try again. Only mark an event as processed after successful handling.

Best practices

Respond quickly, process later

// Good: acknowledge immediately, process in the background
app.post('/webhook', async (req, res) => {
  if (!isValidSignature(req)) {
    return res.status(400).send('Invalid signature');
  }

  // Respond immediately - the sender is waiting
  res.status(200).send('Received');

  // Background processing (queue, worker, or async)
  await processWebhookAsync(req.body);
});

// Bad: blocking processing before responding
app.post('/webhook', async (req, res) => {
  await processPayment(req.body);     // Can take 5s!
  await sendConfirmationEmail();      // + 2s
  await updateInventory();            // + 1s
  res.status(200).send('OK');         // 8 seconds later - timeout risk
});

Retry behavior by status codeWhat is status code?A three-digit number in an HTTP response that tells the client what happened: 200 means success, 404 means not found, 500 means the server broke. Ask AI for more

Event type routing

Always check the event type before processing. A single webhookWhat is webhook?An HTTP request that a service sends to your server when a specific event occurs, like a payment completing. Your server processes the event automatically. Ask AI for more endpointWhat is endpoint?A specific URL path on a server that handles a particular type of request, like GET /api/users. Ask AI for more typically receives many different event types, and handling the wrong type can cause data corruption.

switch (event.type) {
  case 'payment_intent.succeeded':
    await fulfillOrder(event.data.object);
    break;
  case 'payment_intent.payment_failed':
    await notifyCustomer(event.data.object);
    break;
  case 'customer.subscription.deleted':
    await revokeAccess(event.data.object);
    break;
  default:
    console.log(`Unhandled event type: ${event.type}`);
}

Log unhandled event types rather than ignoring them silently. This makes it easy to discover new events you should be handling when you expand your integration.