Visão geral de webhooks · BreezeAuth Docs

Um webhook é uma mensagem que o BreezeAuth envia a um dos seus sistemas assim que algo muda na sua organização. Por exemplo, o BreezeAuth pode avisar o seu sistema no momento em que um usuário entra, um grupo ganha um membro ou uma aplicação é removida.

Sem webhooks, os seus sistemas precisariam perguntar ao BreezeAuth “mudou alguma coisa?” a cada poucos minutos. Com webhooks, o BreezeAuth avisa, na hora.

Para que usar webhooks

Provisionar e desprovisionar contas. Criar uma conta em um sistema interno quando alguém entra na organização, e desativá-la no momento em que a associação da pessoa é excluída.
Manter acessos sincronizados. Replicar membros de grupos ou atribuições de aplicações em outra ferramenta, como uma plataforma de RH, um CRM ou um data warehouse.
Alertar a sua equipe. Avisar a equipe de segurança ou de TI quando um domínio é adicionado ou a configuração de uma aplicação muda.
Alimentar a sua própria trilha de auditoria. Registrar mudanças de identidade no seu sistema de logs ou de conformidade.

Como funciona

Algo mudaUm usuário, grupo, aplicação, atribuição ou domínio é criado, atualizado ou excluído.
O BreezeAuth assina uma mensagemA mensagem diz o que aconteceu e é assinada para que você possa comprovar que veio do BreezeAuth.
O seu endpoint recebeO BreezeAuth envia uma requisição POST para a URL que você cadastrou.
Você confirma o recebimentoO seu endpoint responde com um status 2xx em até 15 segundos. Caso contrário, o BreezeAuth tenta novamente.

Para começar a receber eventos, alguém com permissão para gerenciar webhooks cadastra um endpoint: uma URL do seu lado, junto com a lista de eventos que ela deve receber. Você pode cadastrar vários webhooks, por exemplo um por sistema, cada um com a sua seleção de eventos. Veja Criar e gerenciar webhooks.

O que uma mensagem contém

Cada mensagem descreve um evento e traz apenas os identificadores do que mudou, não os detalhes completos. Por exemplo, quando um usuário é criado, a mensagem informa o identificador da nova associação, mas não o nome ou o e-mail da pessoa. O seu sistema então usa a API do BreezeAuth para buscar os detalhes atuais de que precisa.

{
  "uuid": "6c1f0f8e-4f5b-4a53-9d0e-2b7c9a1e3f42",
  "organizationsUuid": "0d5a7e3c-8b1f-4c2e-a6d9-5f4e3b2a1c0d",
  "timestamp": "2026-10-13T14:32:05.123Z",
  "type": "membership.created",
  "data": {
    "membershipsUuid": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d"
  }
}

Esse formato mantém dados pessoais fora das mensagens e garante que o seu sistema sempre trabalhe com informações atualizadas, mesmo que as mensagens cheguem atrasadas ou fora de ordem. A lista completa de eventos está no catálogo de eventos.

Resumo rápido

Tema	Comportamento
Padrão	Segue a especificação Standard Webhooks, com assinaturas assimétricas.
Transporte	HTTP `POST` com corpo JSON (`Content-Type: application/json`).
Assinatura	Ed25519, enviada no cabeçalho `webhook-signature`. A chave usada é identificada pelo cabeçalho `webhook-keyid`.
IPs de origem	Um conjunto fixo e publicado de endereços, que você pode liberar no seu firewall.
Sucesso	Somente respostas `2xx`. Redirecionamentos (`3xx`) não são seguidos e contam como falha.
Tempo limite	15 segundos por tentativa.
Tentativas	Até 3 por evento: a entrega original e mais 2 novas tentativas, após cerca de 5 e 30 segundos.
Garantia de entrega	Pelo menos uma vez. A mesma mensagem pode chegar mais de uma vez, então o seu endpoint precisa ignorar duplicatas.
Ordem	Não garantida. Use a API para ler o estado atual em vez de depender da ordem das mensagens.
Monitoramento	Toda tentativa fica registrada no Histórico de eventos do webhook, no console de administração.

Responsabilidades do sistema que recebe

Os webhooks só são seguros e confiáveis se o sistema que os recebe seguir algumas regras. Os seus desenvolvedores vão encontrar os detalhes nas próximas páginas; em resumo, o receptor deve:

Verificar a assinatura antes de confiar em qualquer coisa da mensagem. Veja Verificar assinaturas.
Conferir a organização (organizationsUuid) para ter certeza de que a mensagem é destinada a ele.
Ignorar duplicatas, guardando o identificador da mensagem (webhook-id).
Confirmar rapidamente com uma resposta 2xx e fazer o trabalho de fato depois, em segundo plano.
Buscar os detalhes na API em vez de esperar recebê-los na mensagem.

Receber eventos com confiabilidade explica cada regra com exemplos.

Para uma camada extra de proteção, você também pode restringir o seu endpoint para aceitar requisições apenas dos endereços IP do BreezeAuth.

Próximos passos

Crie e gerencie webhooks no console de administração.
Consulte o catálogo de eventos para escolher os eventos de que precisa.
Compartilhe Verificar assinaturas e Receber eventos com confiabilidade com os desenvolvedores que vão construir o seu endpoint.