Webhook Authentication — Complete Developer Guide

Why Webhook Endpoints Need Authentication

A webhook endpoint is a publicly accessible URL — by definition reachable from the internet. Without authentication, anyone who discovers your URL can send arbitrary POST requests to it, potentially triggering business logic, polluting your event queue, or causing unintended side effects.

Webhook authentication solves two distinct problems. The first is authorization: only trusted callers (your partners, your own services, or specific platforms) should be able to deliver events. The second is integrity: the payload hasn't been tampered with in transit. Different authentication methods address these problems in different ways, and choosing the right one depends on whether you control both sides of the integration.

This guide covers the four most common webhook authentication patterns, when to use each, and how to test them using Requex.me's built-in auth testing feature — without writing or running a backend server.

1. Bearer Token Authentication

Bearer token authentication is the most widely-used method for machine-to-machine webhook delivery. The caller includes a secret token in the Authorization header:

POST https://api.requex.me/hook/your-id HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{"event": "order.created", "data": {...}}

The token value is typically either a random opaque string (a pre-shared secret) or a signed JWT (JSON Web Token). For webhook-to-server integrations, opaque secrets are simpler and almost always sufficient — the server just does a constant-time string comparison.

Node.js verification example

const crypto = require('crypto');
const EXPECTED_TOKEN = process.env.WEBHOOK_SECRET;

function verifyBearerToken(req, res, next) {
  const header = req.headers['authorization'] || '';
  const token = header.startsWith('Bearer ') ? header.slice(7) : '';

  // Use timingSafeEqual to prevent timing attacks
  const expected = Buffer.from(EXPECTED_TOKEN);
  const actual   = Buffer.from(token);

  if (actual.length !== expected.length ||
      !crypto.timingSafeEqual(actual, expected)) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
}

2. API Key Authentication

API key authentication is similar to Bearer tokens, but the key is passed in a custom header (such as X-API-Key) or as a query parameter rather than the Authorization header. This is common when the webhook sender is a SaaS platform that has its own API key concept.

POST https://api.requex.me/hook/your-id HTTP/1.1
X-API-Key: sk_live_abc123xyz
Content-Type: application/json

{"event": "payment.success", "amount": 9900}

You configure the header name and expected value in your webhook receiver. Some platforms also support embedding the key in the webhook URL itself as a query parameter (e.g., /hook/your-id?api_key=abc123), though header-based transmission is preferred since query parameters can leak into server logs.

3. Basic Authentication

HTTP Basic Authentication encodes a username and password pair in the Authorization header as a Base64-encoded string. While older than the other methods, many legacy systems and some well-known platforms (like certain Shopify flows) still use it for webhook delivery.

# The header value is: Basic base64("username:password")
POST https://api.requex.me/hook/your-id HTTP/1.1
Authorization: Basic d2ViaG9vazpteXNlY3JldA==
Content-Type: application/json

Verifying Basic Auth in Express

function verifyBasicAuth(req, res, next) {
  const header = req.headers['authorization'] || '';
  if (!header.startsWith('Basic ')) {
    res.setHeader('WWW-Authenticate', 'Basic realm="Webhooks"');
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const decoded = Buffer.from(header.slice(6), 'base64').toString();
  const colonIdx = decoded.indexOf(':');
  const username = decoded.slice(0, colonIdx);
  const password = decoded.slice(colonIdx + 1);

  if (username !== process.env.WH_USER ||
      password !== process.env.WH_PASS) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
}

4. HMAC Signature Verification

HMAC (Hash-based Message Authentication Code) is the gold standard for webhook authentication because it solves both problems simultaneously: it proves the sender knows the shared secret, and it guarantees the payload hasn't been modified in transit. Stripe, GitHub, Shopify, and most serious platforms use HMAC-SHA256.

The sender computes a signature by applying HMAC-SHA256 to the raw request body using a shared secret, then includes the signature in a header. Your receiver performs the same computation and compares the two:

POST https://api.requex.me/hook/your-id HTTP/1.1
X-Webhook-Signature: sha256=c8b4d2e1f3a65d7b9c20e4f...
Content-Type: application/json

{"event": "push", "repository": "my-repo", "commits": [...]}

Verification (Node.js)

const crypto = require('crypto');

function verifyHmacSignature(rawBody, signatureHeader, secret) {
  // Compute expected signature
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)  // must be the raw bytes, not parsed JSON
    .digest('hex');

  // Constant-time comparison prevents timing attacks
  const sigBuffer = Buffer.from(signatureHeader);
  const expBuffer = Buffer.from(expected);

  if (sigBuffer.length !== expBuffer.length) return false;
  return crypto.timingSafeEqual(sigBuffer, expBuffer);
}

// In your Express handler:
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-webhook-signature'];
  if (!verifyHmacSignature(req.body, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const payload = JSON.parse(req.body);
  // Process payload...
  res.sendStatus(200);
});

Comparison: When to Use Each Method

Testing Webhook Authentication with Requex.me

Requex.me lets you configure authentication requirements on your test webhook endpoint and then send test requests to verify your implementation — no server code required. This is useful for:

• Verifying that your sender correctly attaches the expected auth header before going to production.
• Testing rejection behavior — confirming that requests with wrong or missing credentials receive a 401 Unauthorized response.
• Simulating the WWW-Authenticate challenge flow for Basic Auth.
• Validating HMAC signature computation logic by sending a real signed request and checking whether it passes.

Step 1: Open Response Settings

Visit Requex.me to get your unique webhook URL. Click the Response Settings button in the left panel to open the configuration modal.

Step 2: Configure the Auth Tab

Navigate to the Auth tab in the settings modal. Toggle Require Authentication on, then select your method:

Step 3: Save and Test

Click Save to persist your auth configuration. Your endpoint now actively enforces authentication. Send a request with the correct credentials and you'll see it appear in the request log. Send one without — or with a wrong token — and you'll get a 401 with no entry in the log.

# Test with correct Bearer token — should appear in dashboard
curl -X POST https://api.requex.me/hook/your-id \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"event":"test"}'

# Test with wrong token — should return 401 and not appear in dashboard
curl -X POST https://api.requex.me/hook/your-id \
  -H "Authorization: Bearer wrong-token" \
  -H "Content-Type: application/json" \
  -d '{"event":"test"}'

Common Webhook Auth Problems and Fixes

Webhook Authentication Checklist