Skip to main content
Follow these best practices to keep your Brand API webhook integration protected, easy to maintain, and ready for production use.

​
Handle Duplicate Events

Your webhook integration should be idempotent. This means your endpoint can receive the same webhook event multiple times without performing the same action more than once. Use the event urn as a unique idempotency key to identify duplicate events and safely ignore events that have already been processed.

​
Only Listen to Required Events

Configure your webhook endpoint to receive only the event types your integration needs. This helps reduce unnecessary traffic, lowers server processing, and keeps your webhook logic simple. For example, if your application only needs brand update notifications, subscribe only to relevant events such as:
  • brand.updated
  • brand.company.updated

​
Handle Events Asynchronously

If your webhook integration needs to perform long-running tasks, process them asynchronously. Long-running tasks may include:
  • Updating multiple database records
  • Syncing brand data across internal systems
  • Triggering downstream workflows
  • Refreshing cached brand assets
Your endpoint should return a successful 2xx HTTP status code immediately after receiving the event, then process the task in the background using a queue, worker, or background job. This helps prevent webhook timeouts and improves delivery reliability.

​
Verify Event Signatures

We strongly recommend verifying that every webhook event sent to your endpoint actually originated from Brand API. You can verify webhook authenticity by checking the signature included in the webhook-signature header. Signature verification helps protect your integration from unauthorized or fake webhook requests.

​
Example Signature Verification in 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 webhook endpoint must quickly return a successful 2xx HTTP status code before running complex logic that could cause a timeout. Brand API expects your endpoint to respond within a few seconds. If your endpoint takes too long to respond, Brand API may treat the delivery as failed and retry the webhook event later. To improve reliability, receive the event, store it if needed, return a 2xx response, and then process the webhook event asynchronously.