Overview

Get notified of brand data changes by receiving events directly at your webhook URL.

Get notified of brand data changes by receiving events directly at your webhook URL.

Webhooks are available for Enterprise customers. If you are interested in using webhooks, contact us at [e-mail].

Why use webhooks

When building Brand API integrations, your application may need to receive real-time updates when important brand changes happen. Webhooks allow your backend system to receive events automatically, so your application can respond without repeatedly checking the API.

For example, webhooks are useful when:

• A brand logo changes
• Company details are updated
• New brand data is indexed
• A brand profile is re-verified
• Your database needs to stay synchronized with the latest brand information

To enable webhook events, you need to register webhook endpoints. After registration, Brand API can send real-time event data to your application’s webhook endpoint. Brand API sends webhook payloads over HTTPS as a JSON payload that includes an event object. The implementation follows v1 of the Standard Webhooks specification.

Event overview

Brand API implements version 1.0.0 of the Standard Webhooks specification. Brand API generates event data to notify your application about brand activity and data changes.

When an event occurs, Brand API creates a new event object. A single API request may create multiple events. For example, if Brand API re-indexes a brand, your webhook endpoint may receive events such as:

• brand.company.updated
• brand.updated

By registering webhook endpoints with Brand API, you allow Brand API to automatically send event payloads as part of POST requests to the webhook endpoint hosted by your application. After your webhook endpoint receives the event payload, your application can run backend actions, such as updating your database after receiving a brand.updated event.

Event payload

The event object sent to your webhook endpoint provides a snapshot of the object that changed. When available, the payload may also include a delta property that describes the specific change. See the full list of event types available for your webhook configuration.

Example event payload

The following example shows a brand update event where a brand verification status changed.

{
  "type": "brand.updated",
  "timestamp": "2024-01-01T00:00:00.000000Z",
  "urn": "urn:BrandApi:organization:0123:webhook:1234:event:2345",
  "data": {
    "object": {
      "__typename": "Brand",
      "id": "id123456",
      "domain": "brandapi.com",
      "verified": true
    },
    "delta": {
      "verified": {
        "old": false,
        "new": true
      }
    }
  }
}

Event type

You receive events for the event types your webhook endpoint is configured to listen for. Use the received event type to decide what action your application should perform.

The data.object value depends on the event type. In most cases, it represents the main namespace object. For example, for a brand.updated event, the data.object usually represents a Brand object.

Data object and previous attributes delta

Webhook event payloads may include a data.delta property. The data.delta property shows which fields changed and what the previous and new values are.

For *.updated events, the event payload always includes data.delta, allowing your application to inspect exactly what changed on the object.