Webhook

A webhook (also called an HTTP callback or reverse API) is a mechanism where a source application sends an HTTP POST request to a pre-configured URL when a specific event occurs. Unlike traditional APIs (where the consumer polls for data), webhooks push data to the consumer in real time.

How it works:

1. Consumer registers a callback URL with the source service (e.g., https://myapp.com/webhooks/github)
2. An event occurs in the source (push to repo, payment completed, ticket created)
3. Source sends an HTTP POST to the registered URL with a JSON payload describing the event
4. Consumer processes the payload and returns a 2xx status code to acknowledge receipt

Design considerations:

• Idempotency: the same event may be delivered multiple times (at-least-once delivery). Use event IDs to deduplicate.
• Signature verification: validate that the request came from the legitimate source using HMAC signatures (e.g., X-Hub-Signature-256 header).
• Retry logic: if the consumer returns a non-2xx response, the source retries with exponential backoff.
• Timeout: respond quickly (within 5-30 seconds). Queue long-running work for async processing.
• Security: validate signatures, use HTTPS, allowlist source IPs if possible.

Webhook vs. polling vs. WebSocket:

Pattern	Direction	Latency	Use case
Polling	Consumer pulls	High (interval-dependent)	Simple, legacy APIs
Webhook	Source pushes	Low (near-instant)	Event notifications
WebSocket	Bidirectional	Lowest (persistent connection)	Real-time UI, chat

// Express.js webhook handler
import express from "express";
import crypto from "crypto";

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.GITHUB_WEBHOOK_SECRET;

function verifySignature(req) {
  const signature = req.headers["x-hub-signature-256"];
  const hash = "sha256=" + crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(hash)
  );
}

app.post("/webhooks/github", (req, res) => {
  if (!verifySignature(req)) {
    return res.status(401).send("Invalid signature");
  }

  const event = req.headers["x-github-event"];
  if (event === "push") {
    const { ref, commits } = req.body;
    console.log(`Push to ${ref}: ${commits.length} commits`);
    // Queue deployment, notify Slack, etc.
  }

  res.status(200).send("OK");
});