All courses

Webhooks

How to notify your store or ERP when something changes in Bruxel, without anyone having to check.

Video transcript

In this video, you'll see how Bruxel notifies your store or your ERP when something changes, so nobody has to keep checking.

A webhook is an address in your system where Bruxel sends a notice when something happens.

You enter the URL, which has to be public and answer with a 2xx. The one in this video is a test address, so it's blurred.

Then you choose what you want to hear about: here, every real change to a product.

When you register it, you see the secret that signs every notice. It's shown only once, so keep it somewhere safe.

Now we change a product's color. Any real change to a product sends a product.updated notice.

“See deliveries” shows every attempt: when it went out, what your address answered and how long it took.

The detail shows the notice exactly as it went out: the event, the product with its SKU and what changed, never the values. Your system reads the product again.

And if your system missed a notice, “Resend” sends it again, signed again.

Each endpoint shows its last successful delivery and, if it fails, how many failures in a row it has. Bruxel retries on its own.

You can pause it and activate it again. After several failures in a row it turns itself off, and you turn it back on here once it's fixed.

In the next video, you'll see the public API: how another system reads and writes your catalog.

What they are for

A webhook is an address of yours that Bruxel sends a notice to when something happens: a description is ready, an item was published. Your system reacts on its own, instead of someone going in to see whether it is done.

Which events you can listen to

When you register the address you choose what you want to hear about. Only what you asked for is sent, and each notice identifies the product and the language it refers to. `product.updated` fires on any real change to the record — including writing an attribute value — and says what changed (fields and codes, never values): treat it as a wake-up call and re-read the record, or walk the API's change feed.

Signature and secret

Every notice is signed with a secret shown to you ONCE, when you register the webhook. Your system uses that signature to verify the notice comes from Bruxel and not from someone else. If you lose it you can rotate it: the previous one stops working immediately.

When something fails

If your address does not respond, Bruxel retries. Each webhook shows its last success, its last error, and how many consecutive failures it has.

After several consecutive failures the webhook turns itself off. That is deliberate: a dead destination nobody checks piles up retries forever. Once you fix it, turn it back on from the same screen.

Deliveries and calls

On each webhook, «See deliveries» opens the list of every attempt to send it a notification: when it went out, what your address answered (or why it didn't answer) and how long it took. «See details» shows what was sent and what it answered. Administrators can see it.

  • What was sent: the notification exactly as it went out, with its headers. The signature is never kept.
  • What it answered: the first 2 KB of your address's response.
  • Before saving, Bruxel hides anything that looks like a credential (tokens, passwords, keys) and leaves a [•••] mark in its place.

«Resend» sends the same notification again, signed again and with the same X-Bruxel-Delivery. Your system reads the product as it is today, so resending doesn't repeat an old change. It isn't offered if the notification is still in the queue (it will go out on its own), if the webhook is paused or was deleted, or if the 30 days it stays in the queue have passed.

In API Keys, «See calls» opens what each key asked for or wrote about each product through the public API. A write keeps what your system sent and what Bruxel answered (in a bulk upload, for the first products); a read keeps only who called, which route and which code. Lists and feeds aren't recorded.

What is sent and answered is kept for 90 days, up to 1 GB per organization: when it fills up, the oldest go first. Each delivery's and each call's details last up to 13 months (with heavy traffic, the 500,000 most recent of each are kept). An administrator can turn storage off on the same screen; turning it off doesn't delete what was already kept.

Technical detail

The exact notice format, how to verify the signature step by step, and examples in several languages are in the developer portal.