Webhooks

Webhooks allow you to receive notifications when certain events occur in your Sully account.

Webhook Security

Secure your Sully webhook integrations by verifying that incoming requests are authentic. Sully sends an x-sully-signature header with every webhook request, allowing you to validate its integrity.

Structure of the Signature Header

The x-sully-signature header contains:

• Timestamp (t): The time when the request was signed.
• Signature (v1): A hash-based message authentication code (HMAC) signature.

Example:

x-sully-signature:
t=1733782652,
v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Sully generates signatures using HMAC with SHA-256. You can use the steps below to verify these signatures.

Verifying the Webhook Signature

1. Extract the Timestamp and Signature

Parse the x-sully-signature header to retrieve the timestamp (t) and the signature (v1).

function parseSignatureHeader(header: string): { timestamp: string; signature: string } {
  const parts = header.split(',').reduce((acc, part) => {
    const [key, value] = part.split('=');
    if (key && value) acc[key.trim()] = value.trim();
    return acc;
  }, {} as Record<string, string>);

  if (!parts.t || !parts.v1) {
    throw new Error('Invalid signature header format');
  }

  return { timestamp: parts.t, signature: parts.v1 };
}

2. Prepare the signed_payload String

The signed_payload is a concatenation of:

1. The timestamp string.
2. A . (dot) character.
3. The raw body of the webhook request.

function createSignedPayload(timestamp: string, body: string): string {
  return `${timestamp}.${body}`;
}

3. Compute the Expected Signature

Generate the HMAC-SHA256 signature using:

• Key: Your webhook’s signing secret.
• Message: The signed_payload.

import * as crypto from 'crypto';

function computeSignature(secret: string, payload: string): string {
  return crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
}

4. Validate the Signature and Timestamp

1. Constant-time Comparison: Protect against timing attacks by using a secure string comparison.
2. Timestamp Validation: Ensure the timestamp is recent (e.g., within 5 minutes) to mitigate replay attacks.

function isValidSignature(
  header: string,
  body: string,
  secret: string,
  toleranceInSeconds = 300
): boolean {
  const { timestamp, signature } = parseSignatureHeader(header);

  // Validate timestamp
  const currentTime = Math.floor(Date.now() / 1000);
  if (Math.abs(currentTime - parseInt(timestamp, 10)) > toleranceInSeconds) {
    return false;
  }

  // Compute and compare signatures
  const signedPayload = createSignedPayload(timestamp, body);
  const expectedSignature = computeSignature(secret, signedPayload);
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Full Example

import express from 'express';

const app = express();
const SIGNING_SECRET = 'your-webhook-signing-secret';

app.post('/webhook', express.text({ type: '*/*' }), (req, res) => {
  const signatureHeader = req.headers['x-sully-signature'] as string;
  const rawBody = req.body;

  if (!signatureHeader) {
    return res.status(400).send('Missing signature header');
  }

  if (!isValidSignature(signatureHeader, rawBody, SIGNING_SECRET)) {
    return res.status(403).send('Invalid signature');
  }

  // Process the webhook
  res.status(200).send('Webhook received');
});

app.listen(3000, () => console.log('Server is running on port 3000'));

Notes

• Ensure the body passed to isValidSignature is the raw, unparsed payload.
• Adjust the timestamp tolerance (toleranceInSeconds) based on your security requirements.
• Log validation errors for debugging but avoid exposing sensitive details.