Best Practices

Ensure your webhook integration is secure and efficient.

Follow these best practices to ensure your webhook integration remains secure and functions reliably.

Handle Duplicate Events

Your integration should be idempotent, meaning it can handle the same event multiple times without performing the same action more than once. You can use an event’s URN as a unique idempotency key.

Only Listen to Required Events

Configure your webhook endpoint to only receive the event types that your integration requires. This reduces unnecessary traffic and processing on your server.

Handle Events Asynchronously

If your integration needs to perform long-running tasks (like updating multiple database records), it should do so asynchronously. Return a 2xx HTTP status code to [e-mail] immediately upon receiving the event, then process the task in the background.

Verify Event Signatures

We strongly recommend verifying that any event sent to your endpoint actually originated from [e-mail]. You can do this by verifying the signature included in the webhook-signature header.

Example Signature Verification (Node.js)

import crypto from "node:crypto";

const TIMESTAMP_TOLERANCE_MS = 2 * 60 * 1000; // 2 minutes

function verifyWebhookPayload({ secret, headers, rawBody }) {
  const webhookId = headers["webhook-id"];
  const signature = headers["webhook-signature"].split(",")[1];
  const timestamp = Number(headers["webhook-timestamp"]);
  const algorithm = headers["webhook-signature-algorithm"];
  const now = Date.now();

  const expectedSignature = crypto
    .createHmac(algorithm, secret)
    .update(`${webhookId}.${timestamp}.${rawBody}`)
    .digest("hex");

  const isSignatureValid = expectedSignature === signature;
  const isTimestampValid = timestamp < now && timestamp > now - TIMESTAMP_TOLERANCE_MS;

  return isSignatureValid && isTimestampValid;
}

Quickly Return a 2xx Response

Your endpoint must quickly return a successful status code (2xx) prior to any complex logic that could cause a timeout. BrandApi expects a response within a few seconds.