Skip to main content
Signatures provide a method to verify the authenticity and integrity of incoming webhooks. By using a shared secret and a defined verification process, you can ensure that webhooks are genuinely from Surge and haven’t been modified.

​
Surge-Signature header

Each webhook Surge delivers includes a “Surge-Signature” header that looks like this: 
Surge-Signature: t=1737830031,v1=41f947e88a483327c878d6c08b27b22fbe7c9ea5608b035707c6667d1df866dd
Parameters:
  • t: Unix timestamp indicating when webhook was sent
  • v1: Lowercase hex-encoded HMAC-SHA256 signature
    • We may send more than one v1 hash when rolling credentials
Parameter names and values will not include , or =, so these can be split upon to parse the header.

​
Validation Steps

  1. Check timestamp: Verify timestamp is within an acceptable time window (such as 5 minutes) to prevent replay attacks.
  2. Generate payload: The payload signed to create the header is a concatenation of 3 things:
    1. Timestamp from step 1
    2. Period (.)
    3. Raw webhook body
    Example 
    1737830031.{"type":"message.received","id":"evt_01jjfeev3hf9n9c7k5231hd3hr",...}
  3. Compute expected hash: Generate HMAC-SHA256 hash for the payload from step 2.
    • Use the signing secret you received when setting up your webhook endpoint.
  4. Compare hashes: Check computed hash from step 3 with v1 from header.
    • Use constant-time string comparison to protect against timing attacks.
    • There may be multiple v1 parameters in the header
      • Only compare to v1, not other versions which may be added in the future
      • If any of the v1 hashes match, the signature should be accepted as authentic