Webhooks (HTTP Push Notifications & Reverse APIs)

A Webhook (also termed a reverse API or HTTP push callback) is an architectural pattern that enables event-driven, real-time communication between decoupled web applications. Instead of a client polling an API server periodically to check for state updates ("Did anything happen yet?"), the receiving server provides a public endpoint URL where the publishing service initiates an automated HTTP POST request the instant an event occurs ("Payment succeeded", "Build passed", "Customer signed up").

Test, capture, and inspect incoming webhook payloads in real time with our client-side Webhook Tester tool.

---

Technical Specifications at a Glance

Property	Webhooks (Event-Driven Push)	Traditional Polling (Request-Response)
Communication Flow	Server-to-Server asynchronous push	Client-to-Server continuous pull
Transport Protocol	HTTP / HTTPS (Strictly POST or PUT)	HTTP / HTTPS (GET)
Latency	Near zero (Milliseconds after trigger)	Bounded by polling interval (e.g., every 60 seconds)
Server Resource Overhead	Minimal (Executes only when events fire)	High (99%+ of polling requests return empty responses)
Authentication	HMAC signatures in headers (X-Signature)	API Keys, OAuth tokens, Basic Auth
Delivery Guarantees	At-least-once delivery with retry backoff	Client-managed state checkpoints

---

The Anatomy of a Webhook Workflow

[ Third-Party Service (e.g. Stripe / GitHub) ]
                   │
                   │ 1. Event Triggers ("payment.succeeded")
                   │ 2. Computes HMAC SHA-256 Signature
                   ▼
       HTTP POST https://api.devflow.tools/webhooks
       Headers:
         Content-Type: application/json
         X-Signature-SHA256: 3c8e41a...
       Body: { "id": "evt_99", "amount": 4900 }
                   │
                   ▼
[ Receiving App Server ]
  1. Validates HMAC signature using shared secret
  2. Responds immediately with HTTP 200 OK
  3. Enqueues event to background worker queue

---

Webhook Security: Validating HMAC Signatures

Because webhook endpoints are exposed publicly over the internet, attackers can forge fake events. Industry leaders (GitHub, Stripe, Shopify) authenticate payloads using HMAC SHA-256 signatures passed in HTTP headers:

Secure Signature Verification in Node.js / TypeScript

import crypto from 'crypto';

export function verifyWebhookSignature(
  rawBody: string,
  signatureHeader: string,
  secretKey: string
): boolean {
  // Compute expected HMAC SHA-256 hash using shared webhook secret
  const expectedSignature = crypto
    .createHmac('sha256', secretKey)
    .update(rawBody, 'utf8')
    .digest('hex');

  // Prevent timing attacks using constant-time comparison
  const signatureBuffer = Buffer.from(signatureHeader, 'hex');
  const expectedBuffer = Buffer.from(expectedSignature, 'hex');

  if (signatureBuffer.length !== expectedBuffer.length) {
    return false;
  }

  return crypto.timingSafeEqual(signatureBuffer, expectedBuffer);
}

---

Best Practices & Resilience Checklist

1. Always Return HTTP 200 OK Immediately: Webhook providers timeout if an endpoint takes more than 3–5 seconds to respond. Parse the payload, push the job onto a background task queue (e.g., BullMQ, SQS, Celery), and immediately return a 200 response.
2. Implement Idempotency: Webhook networks employ automated retry logic upon network hiccups, meaning your endpoint will eventually receive the same event twice. Store unique event IDs (event.id) in your database with a unique constraint to avoid duplicate billing or duplicate emails.
3. Capture Raw Request Body: Signature verification requires hashing the raw, unparsed byte string. Running the payload through middleware like body-parser can reorder JSON keys and invalidate the cryptographic signature.

---

Frequently Asked Questions

What happens if my server goes down during a webhook delivery?

Reputable webhook providers (such as Stripe and GitHub) employ exponential backoff retry schedules. If your endpoint returns a 5xx error or times out, the service will retry sending the event over the next 24 to 72 hours before marking it failed.

How do Webhooks differ from WebSockets?

Webhooks are server-to-server, stateless HTTP callbacks triggered on discrete events. WebSockets establish a persistent, bidirectional, full-duplex TCP connection between a client browser and a server, ideal for real-time multiplayer games, live chat, or streaming financial tickers.

How do I debug and inspect webhooks locally without public tunneling?

You can simulate requests, verify headers, and inspect formatted JSON payloads directly inside your browser with our client-side Webhook Tester.