Security

How do I verify webhook signatures?

To guarantee that incoming webhooks are legitimately sent by Blockferry and have not been intercepted or tampered with, you should verify the signature before processing payloads.

How Verification Works

1. When you create a webhook subscription, Blockferry generates a unique Signing Secret (prefixed with bf_sec_).

2. Blockferry computes a SHA-256 HMAC signature of the raw request body using this secret.

3. The signature is attached to the request in the X-Blockferry-Signature header, along with a timestamp (X-Blockferry-Timestamp) to prevent replay attacks.

Verification Example (Node.js)

javascript

import crypto from 'crypto';

function verifyBlockferrySignature(req, res, next) {
  const signature = req.headers['x-blockferry-signature'];
  const timestamp = req.headers['x-blockferry-timestamp'];
  const secret = process.env.BLOCKFERRY_SIGNING_SECRET;
  
  if (!signature || !timestamp) {
    return res.status(401).send('Missing signature or timestamp');
  }

  // Prevent replay attacks (5-minute window)
  const fiveMinutesAgo = Math.floor(Date.now() / 1000) - 300;
  if (parseInt(timestamp) < fiveMinutesAgo) {
    return res.status(401).send('Request expired');
  }

  const payload = `${timestamp}.${JSON.stringify(req.body)}`;
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  if (computedSignature !== signature) {
    return res.status(401).send('Invalid signature');
  }

  next();
}