Webhooks

Como avisar sua loja ou seu ERP quando algo muda no Bruxel, sem ninguém precisar conferir.

Este tutorial tem vídeo em outros idiomas: em espanhol · em inglês

Para que servem

Um webhook é um endereço seu para o qual o Bruxel manda um aviso quando algo acontece: uma descrição ficou pronta, uma ficha foi publicada. Seu sistema reage sozinho, em vez de alguém entrar para ver se já saiu.

Quais eventos você pode escutar

Ao registrar o endereço você escolhe do que quer ser avisado. Só é enviado o que você pediu, e cada aviso identifica o produto e o idioma a que se refere. `product.updated` sai de qualquer mudança real da ficha — inclusive ao escrever o valor de um atributo — e diz o que mudou (campos e códigos, nunca valores): use-o como despertador e releia a ficha, ou percorra o feed de mudanças da API.

Assinatura e segredo

Cada aviso vai assinado com um segredo que é mostrado UMA única vez, ao registrar o webhook. Seu sistema usa essa assinatura para conferir que o aviso vem do Bruxel e não de um terceiro. Se você perder, pode rotacioná-lo: o anterior deixa de valer na hora.

Quando algo falha

Se o seu endereço não responde, o Bruxel tenta de novo. Cada webhook mostra o último sucesso, o último erro e quantas falhas seguidas acumulou.

Depois de várias falhas seguidas, o webhook se desliga sozinho. É de propósito: um destino morto que ninguém confere acumula tentativas para sempre. Quando você corrigir, reative pela mesma tela.

Entregas e chamadas

Em cada webhook, «Ver entregas» abre a lista de cada tentativa de enviar um aviso: quando saiu, o que o seu endereço respondeu (ou por que não respondeu) e quanto tempo levou. «Ver detalhe» mostra o que foi enviado e o que foi respondido. Os administradores podem ver.

O que foi enviado: o aviso exatamente como saiu, com seus cabeçalhos. A assinatura nunca é guardada.
O que foi respondido: os primeiros 2 KB da resposta do seu endereço.
Antes de guardar, o Bruxel oculta o que parece uma credencial (tokens, senhas, chaves) e deixa uma marca [•••] no lugar.

«Reenviar» envia de novo o mesmo aviso, assinado de novo e com o mesmo X-Bruxel-Delivery. Seu sistema lê o produto como ele está hoje, então reenviar não repete uma mudança antiga. Não é oferecido se o aviso ainda está na fila (ele vai sair sozinho), se o webhook está pausado ou foi excluído, ou se passaram os 30 dias que ele fica na fila.

Em Chaves de API, «Ver chamadas» abre o que cada chave pediu ou escreveu sobre cada produto pela API pública. Numa escrita fica o que o seu sistema enviou e o que o Bruxel respondeu (numa carga em massa, dos primeiros produtos); numa leitura, só quem chamou, qual rota e qual código. Listas e feeds não são registrados.

O que é enviado e respondido fica guardado 90 dias, até 1 GB por organização: quando enche, os mais antigos saem primeiro. Os dados de cada entrega e de cada chamada duram até 13 meses (com muito tráfego, ficam os 500 mil mais recentes de cada um). Um administrador pode desligar o armazenamento na mesma tela; desligar não apaga o que já foi guardado.

Detalhe técnico

O formato exato do aviso, como verificar a assinatura passo a passo e exemplos em várias linguagens estão no portal de desenvolvedores.