Signed webhooks

• The request was sent by us, and
• The payload has not been modified in transit.

​

Signature headers

X-Signature-HMAC-SHA256-1: 0mzEqDMT92/xvUvgMcogqVix12nSH6NRW+A6nEHy/aQ=
X-Signature-HMAC-SHA256-2: n9V4Qf3bM1l2aBcD4eFgHiJkLmNoPqRsTuVwXyZ0123=

​

How to validate the request

1. Read the raw request body exactly as received.
2. Compute an HMAC-SHA256 digest using each of your active signing keys.
3. Base64 encode each digest.
4. Compare each computed digest against all X-Signature-HMAC-SHA256-* header values.
5. Treat the request as valid if any computed digest matches any header value.
6. Reject the request if no signatures match.

​

Important implementation notes

• Use the raw request body, not a parsed or re-serialised JSON payload.
• Do not modify the request body before computing the signature.
• Signature values are Base64 encoded and may include padding (=).
• More than one signature header may be sent when multiple signing keys are active.
• Do not assume any relationship between the header suffix and a specific signing key.
• Compare the computed and supplied signatures using a secure comparison method.
• Reject requests where no valid signature is present.

​

Key rotation

• webhook requests will include multiple signature headers,
• each signature is generated using a different active key,
• your application should validate the request against all active keys and all supplied headers.

​

Examples

public static string ComputeHash(string secret, string payload)
{
    byte[] bytes = Encoding.UTF8.GetBytes(secret);
    var hmac = new HMACSHA256(bytes);
    bytes = Encoding.UTF8.GetBytes(payload);

    return Convert.ToBase64String(hmac.ComputeHash(bytes));
}

public static bool HashIsValid(string secret, string payload, string verify)
{
    ReadOnlySpan<byte> hashBytes = Convert.FromBase64String(ComputeHash(secret, payload));
    ReadOnlySpan<byte> verifyBytes = Convert.FromBase64String(verify);

    return CryptographicOperations.FixedTimeEquals(hashBytes, verifyBytes);
}

const computeHash = (args) => {
  const hmac = crypto.createHmac('sha256', args.secret);
  hmac.write(args.payload);
  hmac.end();
  return hmac.read().toString('base64');
};

const isHashValid = (args) => {
  return crypto.timingSafeEqual(Buffer.from(args.verify, 'base64'), Buffer.from(computeHash(args), 'base64'));
};