Bruxel integrations: public API, webhooks, Adobe Commerce and custom domain

By Manuel Mattar4 min read

In short

Bruxel connects with your systems in four ways: a REST API with permission-based keys, signed webhooks that notify you when something changes, an Adobe Commerce module that receives published content, and the option to sign in from a subdomain of your company. Every call and every notification is logged.

The problem: the PIM nobody sees

A well-kept catalog is of little use if it reaches the store late, if someone has to log in to check whether a batch finished, or if the ERP learns about changes through a file sent on Fridays. Integration is not a luxury: it is what gets the team's work to where products are sold.

The Bruxel Integrations module brings the pieces together for that, in the Channels menu: Connected systems, Webhooks, API keys and Custom domain.

How it works in Bruxel, step by step

1. The public API

The API is REST and is documented in the developer portal, with a reference, examples in curl, Python and JavaScript, and a changelog. With it your system can push products, read and write attributes, generate descriptions —one by one or in asynchronous batches with an idempotency key—, export the catalog as CSV per language, read channels and know whether a product comes out complete in each one.

Each call carries an API key as a Bearer token. Keys are created in Channels → API keys, by an administrator or the owner; they are shown only once, and each one carries only the permissions (scopes) it needs: read the catalog, write it, generate, export, read channels. Without the permission, the API answers 403. On each key, the calls log shows what it requested or wrote about each product.

2. Webhooks

A webhook is an address of yours that Bruxel notifies when something happens: a description is ready, a product page changed. When you register it you choose which events to listen to, and each notification is signed with a secret shown only once; if it is lost, you rotate it and the previous one stops working.

If your address does not respond, Bruxel retries, and each webhook shows its last success, its last error and how many consecutive failures it has. The deliveries view shows every attempt: what was sent, what your address answered and how long it took, with anything that looks like a credential masked before storing. "Resend" sends the same notification again. The webhooks guide has the details.

3. Connected systems

In "Connected systems" you register the systems in your operation —your store, your ERP, your warehouse— with the key they call with and the endpoint Bruxel notifies. The screen shows when each one last called, how many notifications are waiting to be delivered and whether its channel is healthy. Bruxel flows recognize them by their key. It is visible to operators and above, and it is a feature enabled per account.

4. Adobe Commerce with Bruxel_Sync

If your store runs Adobe Commerce or Magento Open Source 2.4.7, 2.4.8 or 2.4.9, the Bruxel_Sync module is installed with Composer and configured in the Magento admin panel. The module calls Bruxel; Bruxel never gets into your store. The store sends SKU, name, category and the attributes you choose; Bruxel returns the published content, in the store view for each language.

The first sync is the delicate moment, which is why the module ships with two brakes on: a test mode that shows what would change without writing anything, and an option that does not overwrite fields with text that Bruxel never touched. Before writing a field for the first time it saves the previous value, and a command restores it. The Adobe Commerce guide covers the four configuration steps.

5. Custom domain

Your team and your suppliers can sign in from a subdomain of your company, such as pim.yourcompany.com, with your logo on the sign-in page and email links pointing there. You request it from the Bruxel team through the help center; then you create two DNS records (a CNAME and a TXT) and press "Verify now". It costs 100 credits per month per domain. The custom domain guide explains each record.

Who it is for

A hypothetical example: a distributor with its store on Adobe Commerce and an in-house ERP. The store receives descriptions as soon as they are published through Bruxel_Sync, the ERP listens to a webhook and re-reads the product page when it changes, and suppliers sign in through the distributor's subdomain.

It serves teams that already have systems and someone technical who can connect them.

What you need to get started

  • Someone with the administrator or owner role to create keys and register webhooks.
  • A technical person on your system's side: for the API, to receive notifications or to install the module in Magento.
  • For the custom domain, access to your company's DNS and a credit balance.

Honest limits

  • API keys are not scoped by brand or category: they authorize by permissions. A key allowed to write attributes writes across the whole catalog.
  • A webhook turns itself off after several consecutive failures; you have to turn it back on.
  • Bruxel_Sync does not cover stores with several websites without reviewing the mapping by hand, nor Adobe Commerce as a Cloud Service. Images do not travel to the store, and the module's webhook is registered by hand in this version.
  • If you use Content Staging, a scheduled campaign overwrites what Bruxel wrote; you need to publish again afterwards.
  • The custom domain is set up by the Bruxel team for now, and the public API and public pages stay on bruxel.ai.

To see the whole module, open the Integrations page.

Frequently asked questions

Who can create an API key?

An administrator or the organization's owner. The key is shown only once when it is created; Bruxel stores only its hash, so if it is lost you revoke it and create another one.

What happens if my system does not answer a webhook?

Bruxel retries. After several consecutive failures the webhook turns itself off, and you turn it back on from the same screen once the destination responds.

Can the Adobe Commerce module delete my descriptions?

No. It never deletes and never writes the product URL, and out of the box it does not overwrite fields that already have text. It also includes a test mode that shows what would change without writing anything.

Can I use my root domain as a custom domain?

No. It works with a subdomain, such as pim.yourcompany.com. A bare root domain cannot be used.

Sources

  1. Webhook (Wikipedia)
  2. Representational state transfer (Wikipedia)
  3. CNAME record (Wikipedia)

About the author

Manuel Mattar

Founder of Bruxel.AI

In 2014 he founded Wolf Sellers, an e-commerce agency in Mexico City, and later Bruxel.AI, the AI-powered PIM.

See all posts by Manuel Mattar

Try it with your catalog

Create your free account and try Bruxel with your own products using the welcome credits.

Keep reading

Bruxel integrations: public API, webhooks, Adobe Commerce and custom domain