Eventos de domínio

Toda mutação de domínio publica um evento. É isso que impede que os módulos que os consomem se acoplem uns aos outros diretamente — e é daqui que os webhooks de saída tiram os fatos que entregam.

O contrato do outbox

Um evento é escrito na mesma transação das linhas que ele descreve. Essa única regra compra a garantia que importa: um evento nunca descreve uma escrita que sofreu rollback, e uma escrita que comitou nunca deixa de produzir seu evento. Publicar depois do commit tornaria os dois possíveis, e os dois são o tipo de bug que aparece como “o contador está errado às vezes”. Depois do commit, a API cutuca a fila para drenar o outbox. A cutucada é best-effort: ela compra latência. Uma varredura periódica é o que de fato garante a drenagem, mesmo quando toda cutucada se perde.

O que é publicado hoje

Tipo	Agregado	Quando
`organization.created`	`organization`	Uma organização é criada, por cadastro ou por um usuário logado
`member.invited`	`invitation`	Um convite é criado
`member.joined`	`membership`	Um endereço convidado assume a vaga, com uma conta nova ou com a que já tinha
`member.role_changed`	`membership`	O papel de um membro muda
`member.removed`	`membership`	Um membro perde o acesso — removido, ou saiu. O payload diz qual dos dois
`organization.usage_threshold_reached`	`organization`	Os contatos ativos do mês cruzaram 80% ou 100% do limite gratuito
`contact.identified`	`contact`	Um contato deixa de ser só um visitante
`contact.merged`	`contact`	Um contato é absorvido por outro
`contact.signed_in`	`contact`	Uma sessão autenticada foi emitida para um contato identificado, com como (`method`) e de onde (`ip`, `user_agent`)
`contact.email_verified`	`contact`	Um endereço foi provado — um link de verificação, magic link ou código por email voltou da caixa de entrada. Dispara só na transição
`subscription.updated`	`subscription`	Uma assinatura mudou no gateway de pagamento: um status, uma renovação, um cancelamento agendado, uma quantidade
`subscription.plan_changed`	`subscription`	O plano de uma assinatura mudou. Tipo próprio porque é o que um direito acompanha
`subscription.canceled`	`subscription`	Uma assinatura terminou
`invoice.paid`	`invoice`	Uma fatura foi paga
`invoice.payment_failed`	`invoice`	Uma tentativa de pagamento falhou, ou o gateway desistiu da fatura
`invoice.refunded`	`invoice`	Dinheiro voltou numa fatura paga, parcial ou integralmente. O `refunded_minor_total` do payload é o total ACUMULADO do gateway, não o valor deste reembolso — use-o como saldo, nunca somando. A fatura em si não se move: continua `paid` e mantém seu total

Todo evento carrega a organização a que pertence; os do plano de clientes carregam também o ambiente. Os seis eventos de cobrança são o que o gateway diz, espelhado — nunca o que alguém pediu a ele. Mudar de plano pela API é um pedido que o gateway aceita, e qual é o plano depois disso chega com a resposta dele: os eventos acima são publicados quando a cópia local de fato se move, seja porque um webhook chegou, seja porque uma releitura noturna encontrou uma mensagem que nunca chegou. Então dá para construir em cima deles, e eles não são um log de chamadas de API.

`contact.identified` dispara uma vez

Só na transição de verdade. Um segundo magic link é um login, não uma segunda identificação — o SQL que marca o contato como identificado informa se mudou alguma coisa, e o evento só é publicado quando mudou.

Payloads carregam ids

{
  "type": "member.invited",
  "organization_id": "…",
  "aggregate_type": "invitation",
  "aggregate_id": "…",
  "payload": { "role_id": "…", "invited_by": "…" }
}

Ids, não valores. Consumidores releem a linha, o que mantém endereços de e-mail e nomes fora de toda fila, log e buffer de retry por onde o envelope passa. Também significa que um consumidor atrasado lê o estado atual em vez de uma cópia velha.

Entrega é ao menos uma vez, e fora de ordem

Duas propriedades que valem no barramento e valem igual no seu endpoint: a mesma entrega pode chegar duas vezes, e a ordem de chegada não é a ordem dos fatos. Cada envelope carrega uma sequência global atribuída no commit — é ela que ordena, não o relógio da chegada.

Webhooks de saída

Eles são mais um consumidor dos eventos acima, em vez de um segundo caminho de publicação costurado por todo handler — que é justamente o motivo de o barramento vir primeiro, e por que nada da lista mudou de formato quando eles chegaram. O contrato de entrega viaja junto: id para deduplicar, sequence para ordenar. Veja webhooks de saída. Um fato é publicado aqui e deliberadamente nunca entregue para fora, webhook.endpoint_disabled: ele seria endereçado ao endpoint que acabou de parar de responder.

Comece por aqui

Conceitos

Autenticação de contatos

Guias

Eventos de domínio

O contrato do outbox

O que é publicado hoje

`contact.identified` dispara uma vez

Payloads carregam ids

Entrega é ao menos uma vez, e fora de ordem

Webhooks de saída

​O contrato do outbox

​O que é publicado hoje

​contact.identified dispara uma vez

​Payloads carregam ids

​Entrega é ao menos uma vez, e fora de ordem

​Webhooks de saída

O contrato do outbox

O que é publicado hoje

`contact.identified` dispara uma vez

Payloads carregam ids

Entrega é ao menos uma vez, e fora de ordem

Webhooks de saída