Webhook Signature Verification

Documentation Index

Fetch the complete documentation index at: https://developer.finogates.com/llms.txt

Use this file to discover all available pages before exploring further.

• Originated from Finogates
• Was not modified in transit
• Is not a replayed request

​

Required Headers

​

Example

Finogates-Signature: t=1704978452,v1=5f0c2d7f0c0e9b...
Finogates-Signature-Version: 1

​

Obtaining Your Webhook Secret

​

Signature Construction

​

1. Build the Signed Payload

{timestamp}.{raw_request_body}

• timestamp → Unix timestamp (seconds)
• raw_request_body → Exact raw body bytes (no formatting changes)

​

2. Generate HMAC

HMAC_SHA256(secret, signed_payload)

• secret → Your webhook signing secret
• Output → Hex-encoded SHA-256 digest

​

Verification Steps

1. Read the raw request body
2. Parse t and v1 from Finogates-Signature
3. Reject requests older than your allowed time window (recommended: 5 minutes)
4. Recompute the HMAC signature
5. Compare using a constant-time comparison
6. Respond with 200 OK only if verification succeeds

​

Signature Verification Examples

const crypto = require("crypto");

function verifyFinogatesWebhook(req, secret) {
  const signatureHeader = req.headers["finogates-signature"];
  if (!signatureHeader) throw new Error("Missing Finogates-Signature header");

  const parts = Object.fromEntries(
    signatureHeader.replace(/\s/g, "").split(",").map(p => p.split("="))
  );

  const timestamp = parseInt(parts.t, 10);
  const receivedSignature = parts.v1;

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > 300) {
    throw new Error("Webhook timestamp outside allowed window");
  }

  const rawBody = req.rawBody; // MUST be raw bytes
  const signedPayload = `${timestamp}.` + rawBody;

  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");

  if (
    !crypto.timingSafeEqual(
      Buffer.from(expectedSignature),
      Buffer.from(receivedSignature)
    )
  ) {
    throw new Error("Invalid webhook signature");
  }

  return true;
}

​

Security Recommendations

• Always read the raw request body (do not re-serialize JSON)
• Enforce a timestamp tolerance window (recommended: 5 minutes)
• Store your webhook secret securely
• Reject requests with missing or malformed headers
• Respond with 200 OK only after successful verification