Have you ever wondered how services like Stripe can instantly notify your application when a payment succeeds? Or how GitHub can trigger a deployment on your server after a push to the main branch? They don't do it with magic; they use webhooks. ✨

What is a Webhook?

A webhook is sometimes called a "reverse API." Instead of your application continuously asking a service for new data (polling), the service automatically sends—or pushes—data to your application when a specific event occurs.

Analogy:

  • Standard API: You call a pizza place every 5 minutes to ask, "Is my pizza ready yet?" (Polling)
  • Webhook: You give the pizza place your phone number, and they call you as soon as the pizza is ready. (Push notification)

Part 1: Consuming a Webhook

Consuming a webhook is straightforward. It involves three steps:

  1. Build an Endpoint: Create a public URL in your application that can accept POST requests. This URL is your "listener."
  2. Register the Endpoint: You provide this URL to the third-party service (e.g., in your Stripe or GitHub account settings).
  3. Process the Data: When an event happens, the service will send an HTTP POST request with a data payload (usually JSON) to your URL. Your code then processes this payload.

Code Snippet: A Simple Webhook Consumer in Express.js

Let's create a listener that logs incoming webhook data from a hypothetical service.

JavaScript


import express from 'express';

const app = express();

// Use middleware to parse raw request bodies, which is important for verification later
app.use(express.raw({ type: 'application/json' }));

// This is our webhook listener endpoint
app.post('/webhook-listener', (req, res) => {
  console.log('Webhook received!');

  // The raw body is in req.body as a Buffer
  const payload = JSON.parse(req.body.toString());

  // Do something with the payload...
  console.log('Event Type:', payload.event_type);
  console.log('Data:', payload.data);

  // It's crucial to send a 200 OK response quickly
  // to let the service know you received the webhook.
  res.status(200).send('Received');
});

app.listen(3000, () => console.log('Webhook consumer listening on port 3000'));

Part 2: Building a Secure Webhook

If you're building a service that sends webhooks, security is paramount. How does your user know the webhook actually came from you and wasn't faked by a malicious actor? The answer is signature verification.

The process works like this:

  1. Shared Secret: Both you (the sender) and your user (the receiver) share a secret key.
  2. Signing the Payload: Before sending the webhook, you create a cryptographic signature. This is typically an HMAC (Hash-based Message Authentication Code) generated using the secret key and the request payload.
  3. Sending the Signature: You send this signature in a request header (e.g., X-Webhook-Signature).
  4. Verifying on Arrival: The receiver's endpoint performs the same HMAC calculation on the payload they received, using the same shared secret. If their calculated signature matches the one in the header, they can be sure the webhook is authentic and its content hasn't been tampered with.

Code Snippets: Signing and Verifying (Node.js)

Here's how to implement this using Node.js's built-in crypto module.

Sender's Side (Creating the Signature):

JavaScript


import crypto from 'crypto';

const SECRET_KEY = 'my-super-secret-key';
const payload = JSON.stringify({ event_type: 'user.created', data: { id: 1, name: 'Alex' } });

// Create the HMAC signature using SHA256
const signature = crypto
  .createHmac('sha256', SECRET_KEY)
  .update(payload)
  .digest('hex');

// You would then send the `payload` in the request body
// and the `signature` in a header like `X-Webhook-Signature`.
console.log('Signature:', signature);

Receiver's Side (Verifying the Signature in our Express App):

JavaScript


import express from 'express';
import crypto from 'crypto';

const app = express();
const WEBHOOK_SECRET = 'my-super-secret-key'; // The same secret key

// We need the raw body, so we use express.raw()
app.use(express.raw({ type: 'application/json' }));

app.post('/secure-webhook-listener', (req, res) => {
  // Get the signature from the header
  const receivedSignature = req.headers['x-webhook-signature'];
  const requestBody = req.body; // This is a Buffer

  // Recalculate the signature
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(requestBody)
    .digest('hex');

  // Compare the signatures
  if (receivedSignature !== expectedSignature) {
    console.error('Invalid signature!');
    return res.status(400).send('Invalid signature.');
  }

  // If the signature is valid, process the webhook
  const payload = JSON.parse(requestBody.toString());
  console.log('Webhook verified and received!');
  console.log('Data:', payload.data);

  res.status(200).send('Received');
});

app.listen(3000, () => console.log('Secure listener running on port 3000'));