Signature Verification

The X-Signature header contains an HMAC-SHA256 signature of the raw request body (before JSON parsing). To verify the webhook comes from MassAccess:

  1. Get the raw HTTP request body as bytes (do not parse JSON first)
  2. Compute HMAC-SHA256 of the raw body bytes using your API key as the secret
  3. Compare the resulting HEX string with the X-Signature header. Use a constant-time comparison function from your language's standard library (e.g. compare_digest in Python, hash_equals in PHP, timingSafeEqual in Node.js) — not the regular == operator. Constant-time comparison always takes the same amount of time regardless of whether strings match, preventing attackers from guessing the signature by measuring server response time. If they don't match, reject the request — it is forged.

Verify the X-Signature header (HMAC-SHA256) to ensure webhook authenticity:

python
import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    """Verify webhook HMAC-SHA256 signature."""
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)