Webhooks
Cómo avisarle a tu tienda o a tu ERP cuando algo cambia en Bruxel, sin que nadie tenga que revisar.
Transcripción del video
En este video ves cómo Bruxel le avisa a tu tienda o a tu ERP cuando algo cambia, sin que nadie tenga que revisar.
Un webhook es una dirección de tu sistema a la que Bruxel le manda un aviso cuando pasa algo.
Pones la URL, que tiene que ser pública y contestar 2xx. La de este video es una dirección de prueba, por eso va tapada.
Y eliges de qué te quieres enterar: aquí, de cada cambio real en una ficha.
Al registrarlo ves el secreto con el que se firma cada aviso. Se muestra una sola vez: guárdalo en un lugar seguro.
Ahora cambiamos el color de un producto. Cualquier cambio real de la ficha manda un aviso product.updated.
En «Ver entregas» está cada intento: cuándo salió, qué contestó tu dirección y cuánto tardó.
El detalle enseña el aviso tal cual salió: el evento, el producto con su SKU y qué cambió, nunca los valores. Tu sistema relee la ficha.
Y si tu sistema perdió un aviso, «Reenviar» lo manda otra vez, firmado de nuevo.
Cada endpoint dice su última entrega correcta y, si falla, cuántos fallos lleva seguidos. Bruxel reintenta solo.
Lo puedes pausar y volver a activar. Tras varios fallos seguidos se apaga solo, y lo activas desde aquí cuando lo arregles.
En el siguiente video ves la API pública: cómo otro sistema lee y escribe tu catálogo.
Para qué sirven
Un webhook es una dirección tuya a la que Bruxel manda un aviso cuando pasa algo: una descripción quedó lista, una ficha se publicó. Tu sistema reacciona solo, en vez de que alguien entre a ver si ya.
Qué eventos puedes escuchar
Al registrar la dirección eliges de qué te quieres enterar. Solo se te manda lo que pediste, y cada aviso identifica el producto y el idioma al que corresponde. `product.updated` sale de cualquier cambio real de la ficha —también al escribir el valor de un atributo— y dice qué cambió (campos y códigos, nunca valores): úsalo como despertador y relee la ficha, o recorre el feed de cambios de la API.
Firma y secreto
Cada aviso va firmado con un secreto que se te muestra UNA sola vez al registrar el webhook. Tu sistema usa esa firma para comprobar que el aviso viene de Bruxel y no de un tercero. Si lo pierdes, puedes rotarlo: el anterior deja de servir de inmediato.
Cuando algo falla
Si tu dirección no responde, Bruxel reintenta. Cada webhook muestra su último éxito, su último error y cuántos fallos lleva seguidos.
Entregas y llamadas
En cada webhook, «Ver entregas» abre la lista de cada intento de mandarle un aviso: cuándo salió, qué contestó tu dirección (o por qué no contestó) y cuánto tardó. «Ver detalle» enseña lo que se mandó y lo que contestó. Lo ven los administradores.
- Lo que se mandó: el aviso tal cual salió, con sus cabeceras. La firma nunca se guarda.
- Lo que contestó: los primeros 2 KB de la respuesta de tu dirección.
- Antes de guardar, Bruxel tapa lo que parece una credencial (tokens, contraseñas, llaves) y deja una marca [•••] en su lugar.
«Reenviar» manda otra vez el mismo aviso, firmado de nuevo y con el mismo X-Bruxel-Delivery. Tu sistema vuelve a leer el producto como está hoy, así que reenviar no repite un cambio viejo. No se ofrece si el aviso sigue en la cola (va a salir solo), si el webhook está en pausa o se borró, o si pasaron los 30 días que dura en la cola.
En Llaves API, «Ver llamadas» abre lo que cada llave pidió o escribió sobre cada producto por la API pública. En una escritura queda lo que mandó tu sistema y lo que contestó Bruxel (en una carga masiva, de los primeros productos); de una lectura, solo quién llamó, qué ruta y qué código. Las listas y los feeds no se registran.
Detalle técnico
El formato exacto del aviso, cómo verificar la firma paso a paso y ejemplos en varios lenguajes están en el portal de desarrolladores.