What is a Webhook? A Complete Guide for Developers

A webhook is an HTTP POST request sent automatically by one application to another when a specific event occurs. Instead of your application asking "did anything happen?" (polling), the source application tells you "something just happened" (webhook). This event-driven pattern makes webhooks dramatically more efficient than polling for real-time integrations.

How Webhooks Work

Here is the webhook lifecycle in four steps:

1. You register a URL — You give the source application (Stripe, GitHub, Shopify) a public HTTPS endpoint. This is your "webhook URL".
2. An event occurs — A payment succeeds, a pull request is opened, an order is placed.
3. The source sends a POST request — The application sends an HTTP POST to your URL with a JSON body describing the event.
4. Your server responds — You return HTTP 200 to acknowledge receipt. The source retries if you don't respond in time.

Webhook vs API Polling

Polling means your server repeatedly asks "did anything happen?" — every 30 seconds, every minute, every hour. This wastes server resources, delays event processing by up to a full polling interval, and scales poorly with many integrations.

Webhooks are push-based. The source tells you immediately when something happens. No waiting. No wasted requests. Near-real-time data with zero polling overhead.

What a Webhook Payload Looks Like

When Stripe processes a payment, it sends a POST request to your webhook URL with a body like this:

{
  "id": "evt_1NkXxx2eZvKYlo2C7JqKbLSs",
  "object": "event",
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_1NkXxx2eZvKYlo2C7bWJLF6V",
      "amount": 2000,
      "currency": "usd",
      "status": "succeeded"
    }
  },
  "created": 1690000000
}

Webhook Security: Signature Verification

Anyone can POST to a public URL. To verify that a webhook actually came from Stripe (and not an attacker), providers sign every request using HMAC-SHA256. The signature is sent in a request header (e.g., Stripe-Signature). Your server recomputes the expected signature and compares it.

// Node.js — Verify a webhook signature
const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Critical: Always use the raw request body (before JSON parsing) when computing the HMAC. Parsing and re-stringifying changes whitespace and breaks the signature.

Webhook Best Practices

• Respond fast, process async — Return HTTP 200 immediately and process the event in a background job. Most providers timeout after 3–10 seconds.
• Make handlers idempotent — Providers retry on failure. The same event may arrive multiple times. Use the event ID to deduplicate.
• Always verify signatures — Never trust a webhook payload without verifying its HMAC signature.
• Log everything — Webhook debugging is hard without logs. Store the raw payload, headers, and your processing result.
• Handle retries gracefully — Design your handler to process the same event multiple times without side effects.

How to Test Webhooks During Development

The hardest part of webhook development is that you need a public HTTPS URL to receive events — but your local server only listens on localhost. Traditionally, developers used ngrok or localtunnel to expose a local port. But these require installing a CLI, managing a process, and dealing with URLs that change every session.

WebhookWhisper solves this differently: get a permanent public HTTPS URL in your browser, inspect every incoming request in real time, and forward events to your local server via built-in forwarding rules. No install. No tunnel. No CLI.

Frequently Asked Questions

What is the difference between a webhook and an API?

An API is a request-response mechanism — you ask, you receive. A webhook is event-driven — the source notifies you automatically when something happens. APIs are pull-based; webhooks are push-based.

What happens if my webhook endpoint is down?

Most providers retry failed webhook deliveries using exponential backoff — typically 3–10 attempts over 24 hours. If your endpoint is down for an extended period, you may miss events. Always build idempotent handlers so you can safely replay missed events.

Do webhooks require HTTPS?

Yes. All major webhook providers require your endpoint to use HTTPS. HTTP endpoints are rejected for security reasons. WebhookWhisper endpoints are always HTTPS with valid TLS certificates.

How do I test a webhook locally?

Use WebhookWhisper to get a public HTTPS URL, add it to your provider's webhook settings, and set up a forwarding rule to relay events to your local server. No ngrok or CLI needed.