Webhooks

import { createHmac, timingSafeEqual } from 'node:crypto';

/**
 * Verifies the Posdata-Signature header of a webhook delivery.
 *
 * @param {string | undefined} header  Value of the Posdata-Signature header.
 * @param {string | Buffer} rawBody    The request body EXACTLY as received (never re-serialized JSON).
 * @param {string} secret              Your endpoint secret, including the "whsec_" prefix.
 * @param {{ toleranceSec?: number, nowSec?: number }} [options]
 * @returns {boolean} true when the timestamp is recent and at least one v1 signature matches.
 */
export function verifyPosdataSignature(header, rawBody, secret, options = {}) {
  const toleranceSec = options.toleranceSec ?? 300;
  const nowSec = options.nowSec ?? Math.floor(Date.now() / 1000);
  if (!header) return false;

  let timestamp = null;
  const signatures = [];
  for (const part of header.split(',')) {
    const eq = part.indexOf('=');
    if (eq <= 0) continue;
    const key = part.slice(0, eq).trim();
    const value = part.slice(eq + 1).trim();
    if (key === 't' && /^\d+$/.test(value)) timestamp = Number(value);
    else if (key === 'v1' && value) signatures.push(value);
  }
  if (timestamp === null || signatures.length === 0) return false;
  // Reject old (or future) deliveries: this is what stops replays.
  if (Math.abs(nowSec - timestamp) > toleranceSec) return false;

  const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody, 'utf8');
  const expected = createHmac('sha256', secret)
    .update(Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), body]))
    .digest('hex');
  const expectedBuf = Buffer.from(expected, 'utf8');

  // During a secret rotation the header carries two v1 values: accept either.
  let matched = false;
  for (const candidate of signatures) {
    const candidateBuf = Buffer.from(candidate, 'utf8');
    if (candidateBuf.length === expectedBuf.length && timingSafeEqual(candidateBuf, expectedBuf)) {
      matched = true;
    }
  }
  return matched;
}

import express from 'express';
import { verifyPosdataSignature } from './verify.mjs';

const app = express();
const secret = process.env.POSDATA_WEBHOOK_SECRET; // whsec_...

// express.raw keeps the exact bytes: the signature is computed over them.
app.post('/webhooks/posdata', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyPosdataSignature(req.header('Posdata-Signature'), req.body, secret);
  if (!ok) return res.status(400).send('invalid signature');

  const event = JSON.parse(req.body.toString('utf8'));
  // Answer fast; do the real work in the background (queue, job, etc.).
  res.status(200).send('ok');
  queueForProcessing(event);
});

function queueForProcessing(event) {
  // Deduplicate by event.id: the same event can arrive more than once.
  console.log('Posdata event', event.id, event.type);
}

app.listen(3000);

import hashlib
import hmac
import time


def verify_posdata_signature(header, raw_body, secret, tolerance_sec=300, now_sec=None):
    """Verify the Posdata-Signature header of a webhook delivery.

    raw_body must be the request body bytes exactly as received.
    secret is your endpoint secret, including the "whsec_" prefix.
    """
    if not header:
        return False
    if now_sec is None:
        now_sec = int(time.time())
    if isinstance(raw_body, str):
        raw_body = raw_body.encode("utf-8")

    timestamp = None
    signatures = []
    for part in header.split(","):
        key, sep, value = part.partition("=")
        if not sep or not key.strip():
            continue
        key, value = key.strip(), value.strip()
        if key == "t" and value.isdigit():
            timestamp = int(value)
        elif key == "v1" and value:
            signatures.append(value)
    if timestamp is None or not signatures:
        return False
    # Reject old (or future) deliveries: this is what stops replays.
    if abs(now_sec - timestamp) > tolerance_sec:
        return False

    signed = str(timestamp).encode("utf-8") + b"." + raw_body
    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
    # During a secret rotation the header carries two v1 values: accept either.
    matched = False
    for candidate in signatures:
        if hmac.compare_digest(candidate, expected):
            matched = True
    return matched

<?php

/**
 * Verify the Posdata-Signature header of a webhook delivery.
 *
 * $rawBody must be the request body exactly as received: file_get_contents('php://input').
 * $secret is your endpoint secret, including the "whsec_" prefix.
 */
function verify_posdata_signature(?string $header, string $rawBody, string $secret, int $toleranceSec = 300, ?int $nowSec = null): bool
{
    if ($header === null || $header === '') {
        return false;
    }
    $nowSec = $nowSec ?? time();

    $timestamp = null;
    $signatures = [];
    foreach (explode(',', $header) as $part) {
        $eq = strpos($part, '=');
        if ($eq === false || $eq === 0) {
            continue;
        }
        $key = trim(substr($part, 0, $eq));
        $value = trim(substr($part, $eq + 1));
        if ($key === 't' && ctype_digit($value)) {
            $timestamp = (int) $value;
        } elseif ($key === 'v1' && $value !== '') {
            $signatures[] = $value;
        }
    }
    if ($timestamp === null || count($signatures) === 0) {
        return false;
    }
    // Reject old (or future) deliveries: this is what stops replays.
    if (abs($nowSec - $timestamp) > $toleranceSec) {
        return false;
    }

    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    // During a secret rotation the header carries two v1 values: accept either.
    $matched = false;
    foreach ($signatures as $candidate) {
        if (hash_equals($expected, $candidate)) {
            $matched = true;
        }
    }
    return $matched;
}

// Usage:
// $ok = verify_posdata_signature($_SERVER['HTTP_POSDATA_SIGNATURE'] ?? null, file_get_contents('php://input'), getenv('POSDATA_WEBHOOK_SECRET'));
// if (!$ok) { http_response_code(400); exit; }
// http_response_code(200); // answer fast, process in the background