Signature Verification

Every webhook delivery is signed with an HMAC-SHA256 signature computed over the raw request body, using your endpoint’s signing secret as the key.

⚠️

Always verify signatures before trusting an event. Never parse the body first.

Headers

Header	Contents
`VaultsPay-Signature`	`t=<timestamp>,v1=<hex_signature>`
`VaultsPay-Event-Id`	The unique event ID — convenient for dedup.

The t value is the Unix timestamp at which VaultsPay signed the payload. The v1 value is the HMAC signature.

Algorithm

signed_payload = `${t}.${raw_request_body}`
v1 = HMAC-SHA256(signing_secret, signed_payload).hex()

You should:

Split the header to extract t and v1.
Compute the HMAC yourself using the raw body (do not re-encode).
Compare in constant time using crypto.timingSafeEqual (or your language’s equivalent).
Reject events with a t older than 5 minutes to avoid replay attacks.

Example

import crypto from 'crypto'
 
function verifySignature(rawBody, header, secret) {
  if (!header) return false
  const parts = Object.fromEntries(header.split(',').map(kv => kv.split('=')))
  const { t, v1 } = parts
  if (!t || !v1) return false
 
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
 
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex')
 
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
}

import hmac, hashlib, time
 
def verify_signature(raw_body: bytes, header: str, secret: str) -> bool:
    if not header:
        return False
    parts = dict(p.split('=') for p in header.split(','))
    t, v1 = parts.get('t'), parts.get('v1')
    if not t or not v1:
        return False
    if abs(time.time() - int(t)) > 300:
        return False
    msg = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()
    return hmac.compare_digest(v1, expected)

function verify_signature(string $rawBody, string $header, string $secret): bool {
  if (!$header) return false;
  $parts = [];
  foreach (explode(',', $header) as $kv) {
    [$k, $v] = explode('=', $kv, 2);
    $parts[$k] = $v;
  }
  $t = $parts['t'] ?? null;
  $v1 = $parts['v1'] ?? null;
  if (!$t || !$v1) return false;
  if (abs(time() - (int)$t) > 300) return false;
  $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
  return hash_equals($expected, $v1);
}

Rotating the signing secret

You can rotate an endpoint’s signing secret from the dashboard. There’s a 24-hour grace period where both the old and new secrets are valid, to let you deploy.

Event Types Retries & Delivery