Webhooks Guide

What Are Webhooks?

A webhook is an HTTP callback — a POST request that a server sends to a client-configured URL when a specific event occurs. Instead of polling an API repeatedly to check for changes, your application registers a URL and receives event notifications in real time.

Pull vs Push: Polling vs Webhooks

Common Webhook Use Cases

• Payments: Stripe sends payment_intent.succeeded, invoice.paid, charge.refunded
• Version control: GitHub sends push, pull_request, release events
• E-commerce: Shopify sends orders/create, fulfillments/create
• Communications: Twilio sends message delivery status callbacks
• CI/CD: Build systems notify on deployment success or failure

HMAC Signature Verification

Without signature verification, anyone who discovers your webhook URL can send fake events. Webhook providers sign payloads using HMAC-SHA256 with a shared secret that you configure in your provider's dashboard.

How HMAC Signing Works

# Provider (sender) generates signature:
secret = "whsec_your_webhook_secret"
payload = request_body  # raw bytes, before any parsing
signature = HMAC-SHA256(key=secret, message=payload)

# Sends in header:
X-Hub-Signature-256: sha256=abc123def456...
# or for Stripe:
Stripe-Signature: t=1714000000,v1=abc123def456...

Node.js: Verifying Stripe Webhooks

const express = require('express');
const crypto = require('crypto');
const app = express();

// IMPORTANT: Use raw body parser — signature covers raw bytes
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature'];
  const secret = process.env.STRIPE_WEBHOOK_SECRET;

  // Stripe signature format: t=timestamp,v1=signature
  const parts = Object.fromEntries(sig.split(',').map(p => p.split('=')));
  const timestamp = parts.t;
  const receivedSig = parts.v1;

  // Compute expected signature
  const signedPayload = timestamp + '.' + req.body.toString();
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(signedPayload, 'utf8')
    .digest('hex');

  // Use constant-time comparison to prevent timing attacks
  const sigBuffer = Buffer.from(receivedSig, 'hex');
  const expectedBuffer = Buffer.from(expectedSig, 'hex');

  if (sigBuffer.length !== expectedBuffer.length ||
      !crypto.timingSafeEqual(sigBuffer, expectedBuffer)) {
    console.error('Invalid webhook signature');
    return res.status(400).json({ error: 'Invalid signature' });
  }

  // Check timestamp to prevent replay attacks (reject events older than 5 minutes)
  const eventTime = parseInt(timestamp, 10);
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - eventTime) > 300) {
    return res.status(400).json({ error: 'Webhook timestamp too old' });
  }

  const event = JSON.parse(req.body);
  handleWebhookEvent(event);

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

Generic HMAC Verification

function verifyWebhookSignature(rawBody, signature, secret) {
  // signature may be in format "sha256=abc123"
  const hash = signature.startsWith('sha256=')
    ? signature.slice(7)
    : signature;

  const expectedHash = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  // Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(hash, 'hex'),
    Buffer.from(expectedHash, 'hex')
  );
}

Registering Webhooks via REST API

If your platform provides webhooks to customers, you'll need a REST API for managing webhook registrations. Standard patterns:

Webhook Registration Endpoints

# Register a new webhook
POST /webhooks
{
  "url": "https://app.customer.com/webhooks/payments",
  "events": ["payment.succeeded", "payment.failed", "refund.created"],
  "secret": "auto-generated-by-server"
}

→ 201 Created
{
  "id": "wh_abc123",
  "url": "https://app.customer.com/webhooks/payments",
  "events": ["payment.succeeded", "payment.failed", "refund.created"],
  "secret": "whsec_Km9pLqR2xYvNzBdTjW...",  # Show once; store securely
  "active": true,
  "created_at": "2026-04-22T10:00:00Z"
}

# List webhooks
GET /webhooks

# Update events or URL
PATCH /webhooks/wh_abc123
{ "events": ["payment.succeeded"] }

# Delete webhook
DELETE /webhooks/wh_abc123

# Test webhook (send a test event)
POST /webhooks/wh_abc123/test
{ "event_type": "payment.succeeded" }

Security Best Practices for Webhook Registration

• Generate the signing secret on your server — never let the client provide it
• Return the secret only on creation — never include it in subsequent GET responses
• Allow customers to rotate secrets without downtime (support both old and new during a transition window)
• Validate that the target URL is HTTPS and reachable before accepting the registration
• Rate limit webhook deliveries per customer to prevent self-DDoS

Frequently Asked Questions

What happens if my webhook endpoint is down?

The provider will retry the delivery according to their schedule. Ensure your endpoint returns quickly and your infrastructure has high availability. If you're in a maintenance window, most providers allow you to temporarily disable webhook deliveries or catch up via event log APIs (Stripe events API, GitHub delivery logs).

Should I process webhooks synchronously or asynchronously?

Asynchronously, always. Return 200 OK immediately and enqueue the event for background processing. Synchronous processing risks timeouts (causing retries and duplicate deliveries) and couples your webhook availability to your database/service availability.

How do I handle webhook events arriving out of order?

This is a real problem in distributed systems. An order.cancelled event may arrive before order.created due to network delays. Strategies:

• Always fetch the current resource state from the API after receiving a webhook, rather than trusting the payload alone
• Use the event's created timestamp to detect and discard stale events
• Design your state machine to be tolerant of out-of-order transitions

What is the difference between webhooks and WebSockets?

Webhooks are one-way server-to-server HTTP callbacks — your server receives an event when something happens. No persistent connection. Works over standard HTTPS. WebSockets provide a persistent, bidirectional connection between client and server, enabling real-time two-way communication. Use webhooks for server-to-server event notification; use WebSockets for real-time browser UIs (chat, live dashboards).