Verifying webhook signatures

Every webhook Meridian delivers is signed with an HMAC-SHA256 signature, so your endpoint can prove a payload came from Meridian and was not modified in transit.

How signing works#

Before dispatching a delivery, Meridian computes a signature from the exact bytes of the request body and a Unix timestamp, then sends both in the Meridian-Signature header:

1. Concatenate the timestamp, a . separator, and the raw request body.
2. Compute an HMAC-SHA256 digest of that string using your destination’s signing secret as the key.
3. Send the timestamp (t) and hex digest (v1) with the delivery, alongside the event type and delivery ID.

POST /webhooks/meridian HTTP/1.1
Host: api.lumen-billing.com
Content-Type: application/json
Meridian-Event: invoice.payment_succeeded
Meridian-Delivery: dlv_7Kx2mPqR4tNvA9
Meridian-Signature: t=1782431920,v1=9f6b1c2ad84e03f7715c2a9be4d6f0a8c3e5b7d9012f4a6c8e0b2d4f6a8c1e3b

Verify the signature#

Recompute the digest from the raw request body and compare it to v1 with a constant-time comparison. Reject deliveries whose timestamp is more than 300 seconds old to block replay attacks.

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

export function verifySignature(rawBody, header, secret) {
  const { t, v1 } = parseHeader(header);

  // Reject stale timestamps to prevent replay attacks
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${t}.`)
    .update(rawBody)
    .digest("hex");

  return timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

import hmac, hashlib, time

def verify_signature(raw_body: bytes, header: str, secret: str) -> bool:
    t, v1 = parse_header(header)

    # Reject stale timestamps to prevent replay attacks
    if abs(time.time() - int(t)) > 300:
        return False

    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()

    return hmac.compare_digest(v1, expected)

func VerifySignature(rawBody []byte, header, secret string) bool {
    t, v1 := parseHeader(header)

    // Reject stale timestamps to prevent replay attacks
    if time.Now().Unix()-t > 300 || t-time.Now().Unix() > 300 {
        return false
    }

    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(fmt.Sprintf("%d.", t)))
    mac.Write(rawBody)
    expected := hex.EncodeToString(mac.Sum(nil))

    return hmac.Equal([]byte(v1), []byte(expected))
}

Signature header format#

The Meridian-Signature header is a comma-separated list of key=value pairs. Your parser should tolerate unknown keys — new schemes may be added in minor versions.

Troubleshooting#