Eventos

Evento é cada ocorrência enviada para a plataforma por meio do endpoint POST /events.

Enquanto o tipo de evento define o contrato, o evento representa o dado real que aconteceu na sua operação (por exemplo: uma tentativa de pagamento, uma autenticação ou uma atualização de cadastro).

Todo evento pertence a um tipo de evento

Para enviar um evento, é obrigatório informar no atributo type qual tipo de evento ele representa.

Esse valor deve ser o ID de um tipo de evento previamente configurado e ativo na conta.

Se o tipo de evento não existir ou estiver inativo, a API rejeita o envio.

Estrutura mínima de envio

No envio para POST /events, os campos principais são:

type: ID do tipo de evento;
id: identificador único do evento;
attributes: dados do evento conforme os campos configurados no tipo;
timestamp (opcional): data e hora da ocorrência. Se não for informado, a plataforma utiliza o horário do recebimento.

Como a validação funciona

A validação do evento segue as configurações do tipo de evento:

campos obrigatórios precisam ser enviados;
tipos de dados precisam estar no formato esperado;
campos desconhecidos podem ser ignorados ou rejeitados, conforme a configuração do tipo de evento.

Isso garante consistência na ingestão e evita que eventos fora do contrato afetem métricas e monitoramentos.

Exemplo prático

Você cadastra um tipo de evento com ID transaction.
Define os campos esperados, como amount e status.
Envia um evento para POST /events com type: transaction.
A plataforma valida o payload e, se estiver correto, processa o evento para uso em análises, métricas e monitoramentos.