Webhook Signature Verification (HMAC)

To ensure webhook requests are sent by us and have not been modified, we optionally sign webhook payloads using HMAC-SHA256.

To enable this and generate the secret key, go to the Webhook section in the domain settings and generate a secret key.

When enabled, each webhook request will include additional HTTP headers that allow you to verify the authenticity of the request.

1. HTTP Headers

Header Name	Description
X-Signature	HMAC signature of the request payload
X-Timestamp	Unix timestamp (seconds) when the request was generated

Example:

X-Timestamp: 1700000000

X-Signature: sha256=BASE64_SIGNATURE

---

2. Hash Algorithm

• Algorithm: HMAC-SHA256
• Output format: Base64
• Prefix used: sha256=

---

3. Payload Used for Signing

The signature is generated from the following string:

{timestamp}.{raw_request_body}

Example:

1700000000.{"event":"opened","details":{...}}

Important notes:

• The payload is signed exactly as sent
• Do not modify whitespace or formatting before verification
• The request body is UTF-8 encoded

---

4. Character Encoding

• Content-Type: x-www-form-urlencoded

---

5. Example Verification Code

C# Example

public static bool VerifySignature(
   string secret,
   string timestamp,
   string requestBody,
   string receivedSignature)
{
   string payload = timestamp + "." + requestBody;
   byte[] keyBytes = Encoding.UTF8.GetBytes(secret);
   byte[] payloadBytes = Encoding.UTF8.GetBytes(payload);

   using (var hmac = new HMACSHA256(keyBytes))
   {
       byte[] hash = hmac.ComputeHash(payloadBytes);
       string computedSignature =
           "sha256=" + Convert.ToBase64String(hash);

       return SlowEquals(computedSignature, receivedSignature);
   }
}

// Prevent timing attacks
private static bool SlowEquals(string a, string b)
{
   if (a.Length != b.Length)
       return false;

   int diff = 0;
   for (int i = 0; i < a.Length; i++)
       diff |= a[i] ^ b[i];

   return diff == 0;
}

JavaScript (Node.js) Example

const crypto = require("crypto");

function verifySignature(secret, timestamp, body, signature) {

  const payload = `${timestamp}.${body}`;

  const hash = crypto

    .createHmac("sha256", secret)

    .update(payload, "utf8")

    .digest("base64");

  return signature === `sha256=${hash}`;

}

---

6. Timestamp Validation (Recommended)

To prevent replay attacks, we recommend rejecting requests where:

• The timestamp is more than ±5 minutes from your server time

Example:

abs(now - X-Timestamp) > 300 seconds → reject

---

7. When HMAC Is Not Enabled

If webhook signature verification is not enabled in your configuration:

• No X-Signature or X-Timestamp headers will be sent
• Webhooks will continue to work as before

---

Summary

• HMAC is optional
• Designed to be simple and lightweight