Subscribe to Webhook Updates

Fetch a Brand and Subscribe to Real-Time Brand Updates

Webhooks help you keep your local database, cached brand assets, and product UI in sync with the latest Brand API data.

This guide explains how to fetch a brand, create a webhook endpoint, subscribe to brand update events, and unsubscribe when updates are no longer needed.

Use this workflow when your application needs to stay updated when brand data changes, such as logo updates, company metadata changes, or brand profile updates.

Setting Up API Functions

First, define your API helper functions.

You need your Secret API Key from the Brand API dashboard to authenticate requests.

const BRAND_API_SECRET_KEY = "your_secret_key";

async function fetchBrand(domain) {
  const response = await fetch(`https://api.brandapi.io/v2/brands/${domain}`, {
    method: "GET",
    headers: {
      authorization: `Bearer ${BRAND_API_SECRET_KEY}`,
    },
  });

  return response.json();
}

async function graphql(query, variables) {
  const response = await fetch("https://graphql.brandapi.io/", {
    method: "POST",
    headers: {
      authorization: `Bearer ${BRAND_API_SECRET_KEY}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({ query, variables }),
  });

  return response.json();
}

Create a Webhook

Next, register your webhook endpoint so Brand API can send real-time events to your application.

In this example, the webhook listens for brand.updated events.

const webhookEndpointUrl = "https://your-website.com/webhook";

const {
  data: {
    createWebhook: { webhook },
  },
} = await graphql(
  `
    mutation CreateWebhook($createInput: CreateWebhookInput!) {
      createWebhook(input: $createInput) {
        code
        message
        success
        webhook {
          urn
        }
      }
    }
  `,
  {
    createInput: {
      description: "Brand updates",
      enabled: true,
      events: ["brand.updated"],
      url: webhookEndpointUrl,
    },
  }
);

Your webhook endpoint should be publicly accessible over HTTPS and ready to receive POST requests from Brand API.

Retrieve a Brand and Subscribe to Updates

After creating the webhook, fetch the brand you want to monitor.

Then use the brand urn to subscribe your webhook to updates for that specific brand.

// 1. Fetch the brand
const brand = await fetchBrand("google.com");

// 2. Subscribe to updates for this specific brand
await graphql(
  `
    mutation AddWebhookSubscriptions($webhookUrn: URN!, $subscriptions: [URN!]!) {
      addWebhookSubscriptions(
        webhook: $webhookUrn
        subscriptions: $subscriptions
      ) {
        code
        message
        success
      }
    }
  `,
  {
    webhookUrn: webhook.urn,
    subscriptions: [brand.urn],
  }
);

Once subscribed, your webhook endpoint can receive real-time events when the selected brand is updated.

Unsubscribe from Brand Updates

If your application no longer needs updates for a specific brand, remove the subscription from your webhook.

Use the removeWebhookSubscriptions mutation with the webhook urn and the brand urn.

await graphql(
  `
    mutation RemoveWebhookSubscriptions(
      $webhookUrn: URN!
      $subscriptions: [URN!]!
    ) {
      removeWebhookSubscriptions(
        webhook: $webhookUrn
        subscriptions: $subscriptions
      ) {
        code
        message
        success
      }
    }
  `,
  {
    webhookUrn: webhook.urn,
    subscriptions: [brand.urn],
  }
);

Best Use Cases

Subscribing to webhook updates is useful when your application needs fresh brand data without repeatedly polling the API.

Common use cases include:

• Updating cached brand profiles
• Refreshing company logos when they change
• Syncing company metadata with your database
• Keeping CRM records up to date
• Updating fintech merchant or company data
• Triggering backend workflows after brand updates

Recommended Integration Flow

Use this flow for a reliable webhook subscription setup:

1. Create a webhook endpoint in your backend.
2. Register the webhook endpoint with Brand API.
3. Fetch the brand you want to monitor.
4. Subscribe the webhook to the brand urn.
5. Process incoming webhook events asynchronously.
6. Remove subscriptions when they are no longer needed.

This keeps your Brand API webhook integration clean, scalable, and easy to maintain.