Catálogo de eventos

Toda mudança de estado relevante na plataforma gera um Evento imutável. Esse mesmo log alimenta os webhooks: ao assinar um endpoint você escolhe quais tipos quer receber. Esta página é o catálogo completo dos tipos emitidos. A taxonomia é estável e versionada: cada tipo tem um nome recurso.ação, um aggregateType e uma version de schema de payload. Hoje todos os tipos estão em version: 1. A lista também é servida pela API em GET /events/types e é exatamente o conjunto válido para o campo subscribedEvents de um webhook endpoint.

O webhook.test é um tipo sintético: ele é entregue apenas pelo endpoint de teste (POST /webhook-endpoints/{id}/test), mas nunca é registrado no log de eventos nem aparece neste catálogo. Por isso ele é rejeitado se você tentar incluí-lo em subscribedEvents. Veja Visão geral.

Envelope do evento

Todo evento (listado em GET /events, lido em GET /events/{id} ou entregue no body de um webhook) usa o mesmo envelope:

Envelope

{
  "id": "evt_01J9Z6Q0V0T7M9X1A2B3C4D5E6",
  "organizationId": "org_01J9Z6Q0V0T7M9X1A2B3C4D5E6",
  "type": "commission.paid",
  "version": 1,
  "aggregateType": "commission",
  "aggregateId": "comm_01J9Z6Q0V0T7M9X1A2B3C4D5E6",
  "payload": {
    "amountCents": 12500,
    "payoutId": "pay_01J9Z6Q0V0T7M9X1A2B3C4D5E6"
  },
  "metadata": {
    "actor": { "type": "system", "id": "payout-cycle" }
  },
  "occurredAt": "2026-06-13T12:00:00.000Z",
  "recordedAt": "2026-06-13T12:00:00.123Z"
}

string

Identificador evt_ + ULID. O ULID dá ordenação cronológica natural: é o cursor de paginação de GET /events e a chave de deduplicação no recebimento de webhooks.

string

Organização (tenant) dona do evento. Presente nas respostas de GET /events e GET /events/{id}.

string

Tipo namespaced recurso.ação (ex.: commission.paid). Sempre um dos valores deste catálogo.

integer

Versão do schema do payload para aquele type. Hoje sempre 1.

string

Tipo do agregado a que o evento se refere (ex.: commission, payout).

string

ID do agregado (ex.: comm_..., pay_..., aff_...).

object

Snapshot do fato. Pode ser um diff ({ before, after }), a entidade completa ou campos específicos, conforme o tipo.

object

{ actor: { type, id }, source? }. actor.type é user, api_key ou system.

string

Quando o fato ocorreu (ISO-8601). Pode ser definido pelo emissor.

string

Quando o evento foi registrado (ISO-8601).

A entrega de webhook é at-least-once: dedupe pelo campo id do evento. O mesmo envelope pode chegar mais de uma vez após retry ou replay. Veja Retries e dead letter.

Listar a taxonomia pela API

O catálogo abaixo é estático, mas você pode lê-lo em tempo de execução, útil para validar dinamicamente os tipos antes de assinar um endpoint:

cURL

curl https://api.userepass.com/events/types \
  -H "Authorization: Bearer rstr_..."

Resposta (recorte)

{
  "data": [
    { "type": "program.created", "aggregateType": "program", "version": 1, "description": "Program created" },
    { "type": "commission.paid", "aggregateType": "commission", "version": 1, "description": "Commission paid (payout completed)" }
  ]
}

Catálogo por domínio

Os tipos abaixo são o catálogo completo. Os domínios webhook_endpoint.* e reconciliation.* refletem a própria operação dos seus webhooks e a verificação de integridade dos dados; os demais acompanham o ciclo de vida dos recursos de negócio.

program.*: Programas e regras

Agregado program (e commission_rule). Veja Programas e regras.

Tipo	Quando é emitido
`program.created`	Programa criado.
`program.updated`	Configurações do programa atualizadas (payload com diff `{ before, after }`).
`program.activated`	Programa reativado.
`program.paused`	Programa pausado.
`program.archived`	Programa arquivado.
`program.tier_created`	Tier criado (payload `{ tier }`).
`program.tier_updated`	Tier renomeado e/ou reposicionado (payload `{ before, after }`).
`program.tier_reordered`	Tiers reordenados (payload `{ order: tierIds }` na nova ordem).
`program.tier_archived`	Tier arquivado / soft-delete (payload `{ tier }`).
`commission_rule.created`	Nova versão de regra de comissão publicada (padrão do programa ou própria de um tier; `commissionRule.programTierId` identifica o dono).

affiliate.* / terms.*: Afiliados e termos

Agregados affiliate e terms. Veja Afiliados e Termos.

Tipo	Quando é emitido
`affiliate.created`	Afiliado criado.
`affiliate.updated`	Afiliado atualizado (payload com diff).
`affiliate.approved`	Afiliado aprovado.
`affiliate.rejected`	Afiliado rejeitado.
`affiliate.paused`	Afiliado pausado.
`affiliate.resumed`	Afiliado reativado.
`affiliate.banned`	Afiliado banido.
`affiliate.tier_changed`	Tier do afiliado alterado.
`affiliate.terms_accepted`	Afiliado aceitou os termos do programa.
`terms.published`	Nova versão dos termos do programa publicada.

link.* / coupon.*: Divulgação

Agregados link e coupon. Veja Links e cupons.

Tipo	Quando é emitido
`link.created`	Link de rastreamento criado.
`link.updated`	Link atualizado (payload com diff).
`link.deactivated`	Link desativado.
`link.reactivated`	Link reativado.
`link.token_retired`	Token do link aposentado após a janela de reuso.
`coupon.created`	Cupom criado.
`coupon.deactivated`	Cupom desativado.
`coupon.sync_succeeded`	Cupom sincronizado com a plataforma externa de cupons.
`coupon.sync_failed`	Falha ao sincronizar o cupom com a plataforma externa.

click.* / visitor.*: Tracking

Agregados click, visitor e organization (varredura de retenção de IP). Veja Tracking e Atribuição.

Tipo	Quando é emitido
`click.recorded`	Clique registrado.
`click.ips_truncated`	Resumo da varredura de retenção/truncamento de IPs.
`visitor.identified`	Identidade do visitante vinculada a um hash de e-mail.

conversion.* / fraud.*: Conversões e fraude

Agregado conversion. Veja Conversões e fraude.

Tipo	Quando é emitido
`conversion.created`	Conversão criada (payload com snapshots completos).
`conversion.voided`	Conversão anulada.
`conversion.refunded`	Conversão reembolsada (total/chargeback).
`fraud.cleared`	Revisão de fraude liberada (falso positivo).
`fraud.confirmed`	Fraude confirmada pelo operador.

commission.*: Comissões

Agregado commission. Veja Comissões.

Tipo	Quando é emitido
`commission.created`	Comissão criada (vencedor da atribuição, bônus ou ajuste de reprocessamento).
`commission.approved`	Comissão aprovada (job de hold ou manual).
`commission.voided`	Comissão anulada.
`commission.clawback_created`	Clawback criado a partir de um refund.
`commission.review_required`	Comissão sinalizada para revisão manual.
`commission.review_cleared`	Revisão da comissão liberada.
`commission.paid`	Comissão paga (payout concluído).

payout.*: Payouts

Agregado payout. Veja Payouts.

Tipo	Quando é emitido
`payout_batch.created`	Lote de fechamento criado pela rodada de ciclo (agrega os payouts do run).
`payout.created`	Payout agendado pela rodada de ciclo.
`payout.processing`	Execução do payout iniciada.
`payout.completed`	Payout concluído (PIX liquidado).
`payout.failed`	Execução do payout falhou.
`payout.retried`	Payout que falhou foi re-enfileirado.
`payout.canceled`	Payout agendado cancelado.

invoice.*: Fiscal

Agregado invoice. Veja Fiscal.

Tipo	Quando é emitido
`invoice.created`	Obrigação de NF criada junto com o payout.
`invoice.submitted`	Documento de NF enviado.
`invoice.validated`	NF validada.
`invoice.rejected`	NF rejeitada (automática ou manual).
`invoice.reminder_sent`	Cobrança de NF pendente enviada ao afiliado.
`invoice.canceled`	NF cancelada junto com seu payout.

reprocess.*: Reprocessamento

Agregados reprocess_job e commission. Veja Reprocessamento.

Tipo	Quando é emitido
`reprocess.created`	Dry run de reprocessamento criado com o relatório de impacto.
`reprocess.started`	Execução do reprocessamento iniciada.
`reprocess.commission_recalculated`	Comissão recalculada por um job de reprocessamento (payload com `before/after`).
`reprocess.completed`	Execução do reprocessamento concluída.
`reprocess.canceled`	Dry run de reprocessamento cancelado.

settings.*: Configurações

Eventos emitidos quando as configurações da organização mudam.

Tipo	Quando é emitido
`settings.updated`	Configuração da organização atualizada (payload com `before/after`).

webhook_endpoint.*: Webhooks de saída

Agregado webhook_endpoint. Secrets aparecem mascarados (rwhs_***1234) nos payloads. Veja Visão geral e Assinatura.

Tipo	Quando é emitido
`webhook_endpoint.created`	Endpoint criado. Payload: `url`, `subscribedEvents`, `maskedSecret`.
`webhook_endpoint.updated`	Endpoint atualizado. Payload: `diff: { before, after }` (só os campos alterados).
`webhook_endpoint.deleted`	Endpoint removido (hard delete). Payload: `url`.
`webhook_endpoint.secret_rotated`	Secret rotacionado (graça de 24h). Payload: `maskedSecret`, `previousMaskedSecret`, `graceUntil`.
`webhook_endpoint.disabled`	Endpoint auto-desativado por taxa de falha (≥95% em janela de 72h). Payload: `url`, `reason: "failure_rate"`, `windowHours: 72`, `total`, `failures`. Ator `system`.

reconciliation.*: Reconciliação de dados

Verificação diária de integridade que confere se o estado atual dos recursos financeiros (comissões, payouts, conversões e notas fiscais) bate com o histórico de eventos. Ator sempre system. Veja Event store.

Tipo	Quando é emitido
`reconciliation.divergence_found`	Divergência detectada entre o estado atual e o histórico de eventos. Payload: `field` (`status`, `amountCents` ou `orphan`), `expected`, `actual`, `lastEventId?`. `aggregateType` é `commission`, `payout`, `conversion` ou `invoice`.
`reconciliation.completed`	Resumo diário da verificação. Payload: `checked`, `divergenceCount`. `aggregateType` é `organization`.

Atores (`metadata.actor`)

Cada evento carrega quem o originou. O actor.type ajuda a distinguir ações de usuário de processos automáticos:

`actor.type`	Significado	Exemplo de `actor.id`
`user`	Membro autenticado por sessão.	ID do usuário.
`api_key`	Chamada autenticada por API key (`rstr_...`).	ID da chave.
`system`	Processo interno (jobs, dispatcher, reconciliação).	`payout-cycle`, `webhook-dispatcher`, `reconciliation`.

Eventos como payout.*, commission.approved, commission.paid, webhook_endpoint.disabled e os de reconciliation.* são tipicamente emitidos por jobs internos e chegam com actor.type: "system".

Consumindo o catálogo

Há duas formas de consumir esses eventos:

Pull: GET /events

Liste e filtre o log por tipo, agregado, ator e período, com paginação por cursor ULID. O log é um recurso de primeira classe da API.

Push: Webhooks

Assine um subconjunto da taxonomia por endpoint e receba os eventos por HTTP, com assinatura HMAC e retries.

Filtrando o log por tipo

cURL

curl "https://api.userepass.com/events?type=conversion.created&limit=25" \
  -H "Authorization: Bearer rstr_..."

Você também pode filtrar por múltiplos tipos com types repetido, por aggregate_type/aggregate_id, por actor_type e por período (occurred_since inclusivo, occurred_until exclusivo). Para detalhes de parâmetros e do formato de paginação, veja a aba Referência da API, Paginação e Event store.

Assinando um subconjunto em um webhook

O campo subscribedEvents aceita apenas tipos deste catálogo (mínimo de 1). Um tipo desconhecido (inclusive webhook.test) é rejeitado com 400 parameter_invalid.

cURL

curl -X POST https://api.userepass.com/webhook-endpoints \
  -H "Authorization: Bearer rstr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meuapp.com.br/webhooks/repass",
    "subscribedEvents": [
      "conversion.created",
      "conversion.refunded",
      "commission.paid",
      "payout.completed"
    ]
  }'

Próximos passos

Assinatura HMAC

Como verificar o header Repass-Signature e proteger seus endpoints contra replay.

Retries e dead letter

Cronograma de tentativas, auto-disable e replay manual de entregas.

Event store

O log imutável de eventos como recurso de API: filtros, cursor e auditoria.

Conversões server-to-server

Gere conversion.created e seus eventos de comissão a partir do seu backend.

Introdução

Convenções da API

Conceitos

Webhooks & Eventos

Guias

Catálogo de eventos

Envelope do evento

Listar a taxonomia pela API

Catálogo por domínio

Atores (`metadata.actor`)

Consumindo o catálogo

Pull: GET /events

Push: Webhooks

Filtrando o log por tipo

Assinando um subconjunto em um webhook

Próximos passos

Assinatura HMAC

Retries e dead letter

Event store

Conversões server-to-server

​Envelope do evento

​Listar a taxonomia pela API

​Catálogo por domínio

​Atores (metadata.actor)

​Consumindo o catálogo

Pull: GET /events

Push: Webhooks

​Filtrando o log por tipo

​Assinando um subconjunto em um webhook

​Próximos passos

Assinatura HMAC

Retries e dead letter

Event store

Conversões server-to-server

Envelope do evento

Listar a taxonomia pela API

Catálogo por domínio

Atores (`metadata.actor`)

Consumindo o catálogo

Filtrando o log por tipo

Assinando um subconjunto em um webhook

Próximos passos