Setup a Webhook

Start receiving event payloads at your endpoint.

Start receiving event payloads at your endpoint.

To start receiving webhook events in your integration, create and register a webhook endpoint by following the steps below:

1. Create a webhook endpoint handler to receive event data POST requests.
2. Register your endpoint with [e-mail] via an API request.
3. Subscribe to the objects you want to monitor using their URNs.

1. Create a Handler

Set up an HTTPS endpoint that can accept webhook requests with a POST method.

Example endpoint (Node.js/Express):

const express = require('express');
const app = express();

app.post(
  "/webhook",
  express.json({ type: "application/json" }),
  (request, response) => {
    const event = request.body;

    switch (event.type) {
      case "brand.updated":
        const brand = event.data.object;
        const changes = event.data.delta;
        // Handle the brand updated event
        console.log(`Brand updated: ${brand.domain}`);
        break;
      case "brand.verified":
        const verifiedBrand = event.data.object;
        // Handle the brand verified event
        console.log(`Brand verified: ${verifiedBrand.domain}`);
        break;
      default:
        console.log(`Unhandled event type ${event.type}`);
    }

    // Return a 200 response to acknowledge receipt
    response.json({ received: true });
  }
);

app.listen(8000, () => console.log("Running on port 8000"));

2. Register Your Endpoint

Once your handler is ready, register it with [e-mail] using the GraphQL API’s createWebhook mutation.

Mutation:

mutation CreateWebhook($input: CreateWebhookInput!) {
  createWebhook(input: $input) {
    code
    message
    success
    webhook {
      urn
      enabled
    }
  }
}

cURL Example:

curl --request POST \
--header 'content-type: application/json' \
--header 'authorization: Bearer YOUR_API_KEY' \
--url 'https://graphql.brandapi.io' \
--data '{"query":"mutation CreateWebhook($input: CreateWebhookInput!) {\n  createWebhook(input: $input) {\n    code\n    message\n    success\n    webhook {\n      urn\n      enabled\n    }\n  }\n}","variables":{"input":{"description":"My Webhook","events":["brand.updated","brand.verified"],"url":"https://your-app.com/webhook"}}}'

3. Subscribe to Objects

The final step is to subscribe to the specific brands for which you want to receive events.

Mutation:

mutation AddWebhookSubscriptions($webhookUrn: URN!, $subscriptions: [URN!]!) {
  addWebhookSubscriptions(webhook: $webhookUrn, subscriptions: $subscriptions) {
    code
    message
    success
    webhook {
      urn
    }
  }
}

cURL Example:

curl --request POST \
--header 'content-type: application/json' \
--header 'authorization: Bearer YOUR_API_KEY' \
--url 'https://graphql.brandapi.io' \
--data '{"query":"mutation AddWebhookSubscriptions($webhookUrn: URN!, $subscriptions: [URN!]!) {\n  addWebhookSubscriptions(webhook: $webhookUrn, subscriptions: $subscriptions) {\n    code\n    message\n    success\n    webhook {\n      urn\n    }\n  }\n}","variables":{"webhookUrn":"urn:[e-mail]:organization:1234:webhook:5678","subscriptions":["urn:BrandApi:brand:idL0iThUh6"]}}'