Tipos de evento
Um tipo de evento é definido de acordo com um contexto de negócio da sua operação. Exemplos: transação financeira (transaction), autenticação de usuário (user_authentication) ou marcos logísticos de entrega (logistics_delivery_event).
O tipo de evento define o contrato de dados de um evento: como o evento deve ser estruturado, quais dados são relevantes para análise e como esses dados podem ser monitorados ao longo do tempo.
Diferença entre tipo de evento e evento
- tipo de evento: é o modelo de dados e regras de validação.
- evento: é a ocorrência real enviada para a API, seguindo o modelo do tipo de evento.
Todo evento sempre pertence a um tipo de evento previamente configurado.
Na API POST /events, o atributo type do evento informa o ID do tipo de evento cadastrado. Se o tipo informado não existir ou estiver inativo, a plataforma rejeita o envio.
Contrato por contexto de negócio
Com tipo de evento, a integração deixa de depender de um contrato rígido por domínio de negócio e passa a seguir um modelo mais flexível:
- o tipo de evento é definido de acordo com o contexto de negócio;
- os eventos padronizados são enviados para o endpoint
POST /events; - o modelo evolui com menor acoplamento entre produto e integração.
Componentes principais
Um tipo de evento normalmente contempla:
- campos: estrutura do evento (por exemplo: identificadores, valores, status e atributos de contexto);
- métricas: agregações e indicadores derivados dos eventos recebidos;
- monitoramentos: critérios e visões para acompanhamento operacional, risco e performance;
- análises: avaliadores de risco que pontuam o comportamento recente de cada evento;
- regras: lógica avaliada sobre cada evento recebido, no momento em que ele chega.
Essa combinação modela fluxos de negócio diferentes sem um endpoint específico para cada novo caso de uso.
Campos
Os campos definem o contrato de dados do tipo de evento. Consulte Campos para detalhes sobre configuração, tipos de dado e regras de validação.
Análises
As análises acumulam o histórico recente dos eventos em janelas deslizantes e devolvem uma pontuação de risco para cada novo evento, consultada pelas regras. Consulte Análises para a configuração das células, das medidas e dos sinais.
Último evento recebido
O tipo de evento registra o momento em que recebeu o último evento, exibido no painel. É a leitura mais direta para confirmar que uma integração está enviando dados e para identificar um tipo de evento que parou de receber.
Regra padrão
O tipo de evento pode indicar uma regra padrão, aplicada a todos os eventos daquele tipo quando a requisição não informa explicitamente qual regra executar. É a forma recomendada de operar quando existe uma única lógica para o tipo de evento: a integração envia apenas os dados, e a regra passa a ser configuração de painel.
Informar rule.name na requisição sobrepõe a regra padrão.
Relação com a API /events
Depois que um tipo de evento é definido, cada ocorrência é enviada para POST /events seguindo o contrato correspondente.
Esse padrão favorece:
- padronização de ingestão de dados;
- evolução contínua da modelagem;
- reaproveitamento de métricas e monitoramentos entre cenários.
Boas práticas
- Use nomes claros e estáveis para os tipos de evento.
- Evite tipos genéricos demais, sem semântica de negócio.
- Trate mudanças de contrato com versionamento planejado.
- Documente obrigatoriedade e formato de cada campo para o time de integração.