Catálogo de eventos

Ao criar um webhook, você escolhe quais eventos ele recebe. Esta página lista todos os eventos disponíveis, explica quando cada um é enviado e descreve o formato das mensagens.

Formato da mensagem

Toda mensagem tem o mesmo envelope. Apenas o type e o conteúdo de data mudam de um evento para outro.

{
  "uuid": "6c1f0f8e-4f5b-4a53-9d0e-2b7c9a1e3f42",
  "organizationsUuid": "0d5a7e3c-8b1f-4c2e-a6d9-5f4e3b2a1c0d",
  "timestamp": "2026-10-13T14:32:05.123Z",
  "type": "group_assignment.created",
  "data": {
    "groupAssignmentsUuid": "f1e2d3c4-b5a6-4978-8695-a4b3c2d1e0f9",
    "groupsUuid": "9a8b7c6d-5e4f-4321-9876-0fedcba98765"
  }
}

Campo	Descrição
uuid	Identificador único do evento. É o mesmo valor do cabeçalho webhook-id e nunca muda entre as tentativas. Guarde-o para detectar duplicatas.
organizationsUuid	A organização onde o evento aconteceu. Confira-o antes de processar a mensagem.
timestamp	Quando o evento aconteceu, no formato ISO 8601 e em UTC. Não muda entre as tentativas.
type	O tipo do evento, no formato recurso.ação, por exemplo membership.created. Veja a lista de eventos.
data	Os identificadores dos recursos envolvidos. Os campos dependem do tipo de evento.

Somente identificadores, nunca detalhes completos

As mensagens trazem, de propósito, apenas identificadores, nunca nomes, e-mails ou outros atributos. Quando o seu sistema precisa de mais informações, ele as lê na API do BreezeAuth usando esses identificadores. Essa abordagem:

• mantém dados pessoais fora das mensagens, dos logs e das filas;
• garante que o seu sistema sempre aja sobre o estado atual, mesmo que as mensagens cheguem atrasadas, repetidas ou fora de ordem;
• mantém as mensagens pequenas e estáveis quando novos atributos são adicionados ao produto.

Quando um evento envolve um recurso que existe dentro de outro, data também traz o identificador do recurso pai. Por exemplo, uma atribuição de aplicação vem acompanhada do identificador da aplicação, porque ambos são necessários para ler a atribuição na API.

Eventos disponíveis

No campo Eventos do console de administração, os eventos aparecem com nomes legíveis, como Associação criada. Nas mensagens, o campo type usa o nome técnico, como membership.created.

Associações (usuários)

Uma associação é o vínculo de um usuário com a sua organização. Veja Conceitos de IAM.

Evento	Enviado quando	Campos de data
membership.created	Um usuário entra na organização (convidado, provisionado ou criado).	membershipsUuid
membership.updated	O perfil, o papel ou o status de um usuário muda, como uma suspensão.	membershipsUuid
membership.deleted	Um usuário é removido da organização.	membershipsUuid

Grupos

Evento	Enviado quando	Campos de data
group.created	Um grupo é criado.	groupsUuid
group.updated	Os dados de um grupo, como o nome, mudam.	groupsUuid
group.deleted	Um grupo é excluído.	groupsUuid

Quando um grupo é excluído, as atribuições de aplicação dele são removidas junto, e nenhum evento application_assignment.deleted separado é enviado para elas. Trate group.deleted como o fim de qualquer acesso a aplicações concedido por meio desse grupo.

Atribuições de grupo

Uma atribuição de grupo torna um usuário, ou outro grupo, membro de um grupo. Veja Membros do grupo.

Evento	Enviado quando	Campos de data
group_assignment.created	Um membro é adicionado a um grupo.	groupAssignmentsUuid, groupsUuid
group_assignment.deleted	Um membro é removido de um grupo.	groupAssignmentsUuid, groupsUuid

groupsUuid identifica o grupo que ganhou ou perdeu o membro.

Com grupos aninhados, os eventos também são enviados para associações indiretas: adicionar o grupo “Backend” a “Engenharia” envia um evento group_assignment.created para “Backend” e um para cada membro dele que passa a ser membro de “Engenharia”. Nenhum evento é enviado quando uma associação existente apenas muda entre direta e indireta.

Aplicações

Evento	Enviado quando	Campos de data
application.created	Uma aplicação é cadastrada na organização.	applicationsUuid
application.updated	A configuração de uma aplicação muda.	applicationsUuid
application.deleted	Uma aplicação é removida.	applicationsUuid

Atribuições de aplicação

Uma atribuição de aplicação dá a um usuário ou grupo acesso a uma aplicação.

Evento	Enviado quando	Campos de data
application_assignment.created	Um usuário ou grupo recebe acesso a uma aplicação.	applicationAssignmentsUuid, applicationsUuid
application_assignment.updated	Uma atribuição muda, por exemplo os seus papéis ou atributos.	applicationAssignmentsUuid, applicationsUuid
application_assignment.deleted	O acesso de um usuário ou grupo a uma aplicação é removido.	applicationAssignmentsUuid, applicationsUuid

Domínios

Evento	Enviado quando	Campos de data
domain.created	Um domínio é adicionado à organização.	domainsUuid
domain.updated	Um domínio muda, por exemplo quando a sua verificação é concluída.	domainsUuid
domain.deleted	Um domínio é removido.	domainsUuid

Sobre os eventos de atualização

Os eventos *.updated só são enviados quando algo relevante muda. Controles internos, como a alteração apenas da data de modificação de um registro, não geram eventos.

Uma mensagem de atualização não informa quais campos mudaram. Se o seu sistema precisa reagir a uma mudança específica, como o departamento de um usuário, guarde uma cópia dos valores que interessam e compare-os com os dados atuais da API.

Escolhendo os eventos

Assine apenas os eventos que o sistema receptor realmente usa. Menos eventos significam menos tráfego para o seu endpoint e um histórico de eventos mais claro. Mesmo assim, o seu endpoint deve responder 2xx a qualquer tipo de evento que não reconheça, porque novos tipos podem ser adicionados no futuro e você pode assiná-los depois.