What Are Webhooks? A Developer's Complete Guide

If you're building modern web applications, you'll inevitably encounter webhooks. They're the backbone of real-time integrations between services — from payment processing to CI/CD pipelines. Let's break down what they are and how to work with them.

Webhooks Explained

A webhook is an HTTP callback: an HTTP POST request sent by one application to another when a specific event occurs. Instead of continuously polling an API to check for changes, the service pushes data to you automatically.

Polling vs Webhooks

Polling: "Hey Stripe, did anyone pay yet?" (repeated every 30 seconds)

Webhooks: "Stripe sends you a POST request the moment someone pays."

Webhooks are more efficient, faster, and use fewer resources than polling.

How Webhooks Work

1. You register a URL with the service (e.g., https://yourapp.com/webhooks/stripe)
2. An event occurs (e.g., a customer completes a purchase)
3. The service sends an HTTP POST to your URL with event data as JSON
4. Your server processes the event and returns a 200 OK

Common Webhook Providers

• Stripe — Payment events (charges, subscriptions, invoices)
• GitHub — Repository events (pushes, pull requests, issues)
• Shopify — E-commerce events (orders, products, customers)
• Twilio — Communication events (SMS received, calls)
• Slack — Workspace events (messages, reactions)

A Simple Webhook Receiver

Here's a basic webhook receiver in Node.js with Express:

app.post('/webhooks/stripe', (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'checkout.session.completed':
      // Fulfill the purchase
      handleCheckoutComplete(event.data.object);
      break;
    case 'invoice.paid':
      // Continue the subscription
      handleInvoicePaid(event.data.object);
      break;
  }

  res.status(200).json({ received: true });
});

Webhook Security

Anyone can send a POST request to your endpoint, so you need to verify that requests genuinely come from the expected service. Most providers use HMAC signatures:

1. The provider signs the request body with a shared secret
2. The signature is included in a header (e.g., Stripe-Signature)
3. Your server computes the same HMAC and compares

Tools like HookSense can automatically verify these signatures for you during development.

Common Challenges

• Local development — Your localhost isn't accessible from the internet. Use tools like HookSense CLI to forward webhooks locally.
• Debugging — You can't see what's in the request without logging. Use a webhook inspector to view headers, body, and metadata.
• Retries — If your server returns a non-2xx response, providers will retry. Handle idempotency to avoid processing the same event twice.
• Order — Events may arrive out of order. Use timestamps or sequence numbers when available.

Testing Webhooks with HookSense

Instead of setting up complex local tunnels or reading JSON in terminal logs, you can use HookSense to:

1. Create a free endpoint at hooksense.com
2. Point your webhook provider to the HookSense URL
3. View every request in real-time with a clean web UI
4. Replay requests to test your handler after making changes
5. Forward webhooks to your local server with the CLI

Get started for free — no credit card required.

Related

• HMAC Webhook Signature Verification Guide
• How to Test Stripe Webhooks Locally
• HookSense Documentation