Criar e gerenciar webhooks · BreezeAuth Docs

Os webhooks são configurados por organização, no console de administração do BreezeAuth. Esta página mostra cada passo. Não é preciso programar para configurar um webhook, mas alguém do seu lado precisa fornecer a URL do endpoint: o endereço do sistema que vai receber as mensagens.

Antes de começar

Permissões. Você precisa de permissão para visualizar e gerenciar webhooks na sua organização. Se a aba Webhooks estiver desabilitada, ou se o botão Adicionar webhook não aparecer, fale com um administrador da sua organização.
Uma URL de endpoint. Os seus desenvolvedores fornecem esse endereço, por exemplo https://exemplo.com.br/webhooks/breezeauth. Antes de ativar o webhook em produção, o endpoint já deve ser capaz de verificar assinaturas e de confirmar as mensagens rapidamente.
Firewall (opcional). Se a sua equipe de rede restringe o tráfego de entrada, ou se você quiser fazer isso, libere o acesso ao endpoint para os endereços IP do BreezeAuth. As requisições desses endereços não podem ser bloqueadas, ou as entregas vão falhar.

Dica: use uma URL https://. O BreezeAuth também aceita http://, mas nesse caso as mensagens trafegam sem criptografia pela internet.

Encontrar os webhooks da sua organização

Entre no console de administração.
Na barra lateral, selecione Organização. A página Gerenciar Organização é aberta.
Selecione a aba Webhooks.

A lista mostra todos os webhooks cadastrados na organização, com a URL, o Status (Ativado ou Desativado), os Eventos assinados e a data de criação. Selecione uma linha para abrir os detalhes do webhook.

Criar um webhook

Na aba Webhooks, selecione Adicionar webhook. O formulário Novo webhook é aberto.
Preencha os campos descritos abaixo.
Selecione Criar webhook.

Campo	Descrição
Nome	Um rótulo para reconhecer o webhook, por exemplo “Sistema de RH” ou “Eventos de faturamento”. Até 255 caracteres. Só aparece para você.
URL	O endereço que vai receber as mensagens. Até 255 caracteres. Redirecionamentos não são seguidos, então informe o endereço final (veja Entrega e novas tentativas).
Eventos	Os eventos que este endpoint recebe. Escolha apenas os que o sistema receptor precisa. Veja o catálogo de eventos. Um webhook sem eventos selecionados não recebe nada.
Ativado	Quando marcado (o padrão), os eventos são enviados. Desmarque para pausar as entregas sem perder a configuração.

A partir daí, todo evento assinado na organização é entregue à URL em poucos segundos.

Observação: cada webhook recebe a sua própria cópia de cada evento que assina. Se dois webhooks apontarem para a mesma URL e assinarem o mesmo evento, essa URL recebe o evento duas vezes, com o mesmo identificador de evento.

Editar um webhook

Abra o webhook a partir da aba Webhooks.
Selecione Atualizar.
Altere o nome, a URL, os eventos ou a opção Ativado e selecione Salvar alterações.

As alterações valem imediatamente, inclusive para novas tentativas que ainda estejam pendentes:

Se você desativar o webhook, ou remover um evento da lista, as novas tentativas pendentes desse webhook ou evento são canceladas.
Se você alterar a URL, as próximas tentativas vão para a nova URL.

Pausar as entregas

Para interromper as entregas temporariamente, por exemplo durante uma manutenção do sistema receptor, edite o webhook e desmarque Ativado. Os eventos que acontecem enquanto o webhook está desativado não ficam guardados para depois: eles simplesmente não são enviados. Quando você reativar o webhook, apenas os novos eventos serão entregues. O seu sistema pode recuperar o que perdeu lendo os dados atuais pela API (veja Receber eventos com confiabilidade).

Excluir um webhook

Abra o webhook a partir da aba Webhooks.
Selecione Excluir.
Confirme na janela Excluir webhook.

Importante: a exclusão de um webhook não pode ser desfeita. As entregas param imediatamente e o histórico de eventos do webhook deixa de estar disponível no console de administração. Se você só precisa interromper as entregas por um tempo, desative o webhook.

Conferir o que foi enviado

A página de detalhes de cada webhook mostra o seu Histórico de eventos: cada tentativa de entrega, se deu certo e, caso contrário, o motivo. Veja Histórico de eventos.

As alterações são auditadas

A criação, a atualização e a exclusão de webhooks ficam registradas nos Logs de Auditoria da sua organização, junto com quem fez a alteração e quando.