Webhook Signing and Verification (HMAC)

// Provider-side signing
const crypto = require('crypto');

function signWebhook(payload, secret) {
    // Use the raw JSON string, not the parsed object
    const rawBody = typeof payload === 'string'
        ? payload
        : JSON.stringify(payload);

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

    return {
        signature: `sha256=${signature}`,
        rawBody,
    };
}

// Usage
const webhookSecret = 'whsec_abc123def456';
const eventPayload = {
    event: 'payment.succeeded',
    data: { id: 'pi_123', amount: 5000 },
};

const { signature, rawBody } = signWebhook(eventPayload, webhookSecret);

// Headers to send with the POST request
const headers = {
    'Content-Type': 'application/json',
    'X-Webhook-Signature': signature,
};

// Consumer-side verification (Node.js)
const express = require('express');
const crypto = require('crypto');

const app = express();
const WEBHOOK_SECRET = 'whsec_abc123def456';

// Capture raw body for signature verification
app.use(express.json({
    verify: (req, res, buf) => {
        req.rawBody = buf.toString();
    },
}));

app.post('/webhooks/payment', (req, res) => {
    const signature = req.headers['x-webhook-signature'];
    const timestamp = req.headers['x-webhook-timestamp'];

    // 1. Verify signature
    if (!verifySignature(req.rawBody, signature, WEBHOOK_SECRET)) {
        console.error('Invalid signature');
        return res.status(401).send('Invalid signature');
    }

    // 2. Check timestamp (prevent replay)
    const age = Date.now() - new Date(timestamp).getTime();
    if (age > 300000) { // 5 minutes
        console.error('Webhook too old');
        return res.status(400).send('Stale webhook');
    }

    // 3. Process validated webhook
    res.status(200).send('OK');
    setImmediate(() => processPayment(req.body));
});

function verifySignature(rawBody, signatureHeader, secret) {
    if (!signatureHeader || !rawBody) return false;

    // Extract the actual hex digest from "sha256=abc123..."
    const expectedSig = signatureHeader.startsWith('sha256=')
        ? signatureHeader.slice(7)
        : signatureHeader;

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

    // Use timing-safe comparison
    return timingSafeEqual(computedSig, expectedSig);
}

function timingSafeEqual(a, b) {
    if (a.length !== b.length) {
        return false;
    }
    return crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
}

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = b'whsec_abc123def456'

@app.route('/webhooks/payment', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    timestamp = request.headers.get('X-Webhook-Timestamp')
    raw_body = request.get_data(as_text=True)

    if not verify_signature(raw_body, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    # Check timestamp
    # (parse ISO timestamp, check age)

    return 'OK', 200

def verify_signature(raw_body, signature_header, secret):
    if not signature_header or not raw_body:
        return False

    if signature_header.startswith('sha256='):
        expected_sig = signature_header[7:]
    else:
        expected_sig = signature_header

    computed_sig = hmac.new(
        secret,
        raw_body.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(computed_sig, expected_sig)

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "io"
    "net/http"
    "strings"
)

var webhookSecret = []byte("whsec_abc123def456")

func verifySignature(rawBody string, signatureHeader string) bool {
    if signatureHeader == "" || rawBody == "" {
        return false
    }

    expectedSig := strings.TrimPrefix(signatureHeader, "sha256=")

    mac := hmac.New(sha256.New, webhookSecret)
    io.WriteString(mac, rawBody)
    computedSig := hex.EncodeToString(mac.Sum(nil))

    return hmac.Equal([]byte(computedSig), []byte(expectedSig))
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    signature := r.Header.Get("X-Webhook-Signature")

    if !verifySignature(string(body), signature) {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    w.WriteHeader(http.StatusOK)
    w.Write([]byte("OK"))
}

// Support multiple secrets for rotation
class WebhookSecretManager {
    constructor() {
        this.secrets = new Map();
        this.currentVersion = 1;
        this.rotationInterval = 90 * 24 * 60 * 60 * 1000; // 90 days
    }

    addSecret(version, secret) {
        this.secrets.set(version, secret);
    }

    getCurrentSecret() {
        return this.secrets.get(this.currentVersion);
    }

    getSecretByVersion(version) {
        return this.secrets.get(version);
    }

    rotateSecret() {
        const newVersion = this.currentVersion + 1;
        const newSecret = generateSecret();
        this.addSecret(newVersion, newSecret);

        // Keep old secret for overlap period
        console.log(`Rotated to secret v${newVersion}`);

        // Schedule old secret removal
        setTimeout(() => {
            this.secrets.delete(this.currentVersion);
            console.log(`Old secret v${this.currentVersion} removed`);
        }, this.rotationInterval);

        this.currentVersion = newVersion;
    }

    verifyWithRotation(rawBody, signatureHeader) {
        // Try all active secrets
        for (const [version, secret] of this.secrets) {
            if (verifySignature(rawBody, signatureHeader, secret)) {
                return { valid: true, version };
            }
        }
        return { valid: false };
    }
}

function generateSecret() {
    return crypto.randomBytes(32).toString('hex');
}