Validating Webhook Requests with Secrets

To ensure your server only processes webhook requests sent by RiskBase and to ensure the payload was not tampered with, you should validate the webhook signature before processing the webhook request further.

To use this feature, enter a secret token of your choice when setting up (or updating) your webhook. Your secret should be a random string of text with high entropy.

Validating Webhook Requests

RiskBase uses your secret token and the request's payload to create a hash signature. The hash signature will appear in each request as the HTTP header:

{
  'X-RB-Signature-256': '{hash signature}'
}

In your code that handles webhook requests, you should calculate a hash using your secret token. Then, compare the hash that RiskBase sent with the expected hash that you calculated, and ensure they match.

RiskBase uses an HMAC hex digest to compute the hash. Instead of using a basic string comparison, use a method like crypto.timingSafeEqual, used to determine whether two variables are equal without exposing timing information that may allow an attacker to guess one of the values.

Example Code

import * as crypto from "crypto";

const WEBHOOK_SECRET: string = process.env.WEBHOOK_SECRET;

const verify_signature = (req: Request) => {
  const signature = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest("hex");
  const trusted = Buffer.from(signature, 'ascii');
  const untrusted =  Buffer.from(req.headers.get("x-rb-signature-256"), 'ascii');
  return crypto.timingSafeEqual(trusted, untrusted);
};

const handleWebhook = (req: Request, res: Response) => {
  if (!verify_signature(req)) {
    res.status(401).send("Unauthorized");
    return;
  }
  // Continue processing webhook request...
};