> ## Documentation Index
> Fetch the complete documentation index at: https://userepass.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Catálogo de eventos

> Todos os tipos de evento emitidos pelo Repass.

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.

<Info>
  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](/docs/webhooks/visao-geral).
</Info>

## 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:

```json Envelope theme={null}
{
  "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"
}
```

<ResponseField name="id" type="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.
</ResponseField>

<ResponseField name="organizationId" type="string">
  Organização (tenant) dona do evento. Presente nas respostas de `GET /events` e `GET /events/{id}`.
</ResponseField>

<ResponseField name="type" type="string">
  Tipo namespaced `recurso.ação` (ex.: `commission.paid`). Sempre um dos valores deste catálogo.
</ResponseField>

<ResponseField name="version" type="integer">
  Versão do schema do payload para aquele `type`. Hoje sempre `1`.
</ResponseField>

<ResponseField name="aggregateType" type="string">
  Tipo do agregado a que o evento se refere (ex.: `commission`, `payout`).
</ResponseField>

<ResponseField name="aggregateId" type="string">
  ID do agregado (ex.: `comm_...`, `pay_...`, `aff_...`).
</ResponseField>

<ResponseField name="payload" type="object">
  Snapshot do fato. Pode ser um diff (`{ before, after }`), a entidade completa ou campos específicos, conforme o tipo.
</ResponseField>

<ResponseField name="metadata" type="object">
  `{ actor: { type, id }, source? }`. `actor.type` é `user`, `api_key` ou `system`.
</ResponseField>

<ResponseField name="occurredAt" type="string">
  Quando o fato ocorreu (ISO-8601). Pode ser definido pelo emissor.
</ResponseField>

<ResponseField name="recordedAt" type="string">
  Quando o evento foi registrado (ISO-8601).
</ResponseField>

<Tip>
  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](/docs/webhooks/retries-e-dead-letter).
</Tip>

## 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:

```bash cURL theme={null}
curl https://api.userepass.com/events/types \
  -H "Authorization: Bearer rstr_..."
```

```json Resposta (recorte) theme={null}
{
  "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.

<AccordionGroup>
  <Accordion title="program.*: Programas e regras" icon="layer-group">
    Agregado `program` (e `commission_rule`). Veja [Programas e regras](/docs/conceitos/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). |
  </Accordion>

  <Accordion title="affiliate.* / terms.*: Afiliados e termos" icon="user-group">
    Agregados `affiliate` e `terms`. Veja [Afiliados](/docs/conceitos/afiliados) e [Termos](/docs/conceitos/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. |
  </Accordion>

  <Accordion title="link.* / coupon.*: Divulgação" icon="link">
    Agregados `link` e `coupon`. Veja [Links e cupons](/docs/conceitos/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. |
  </Accordion>

  <Accordion title="click.* / visitor.*: Tracking" icon="mouse-pointer">
    Agregados `click`, `visitor` e `organization` (varredura de retenção de IP). Veja [Tracking](/docs/conceitos/tracking) e [Atribuição](/docs/conceitos/atribuicao).

    | 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. |
  </Accordion>

  <Accordion title="conversion.* / fraud.*: Conversões e fraude" icon="cart-shopping">
    Agregado `conversion`. Veja [Conversões e fraude](/docs/conceitos/conversoes-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.                    |
  </Accordion>

  <Accordion title="commission.*: Comissões" icon="coins">
    Agregado `commission`. Veja [Comissões](/docs/conceitos/comissoes).

    | 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).                                             |
  </Accordion>

  <Accordion title="payout.*: Payouts" icon="money-bill-transfer">
    Agregado `payout`. Veja [Payouts](/docs/conceitos/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.                                                 |
  </Accordion>

  <Accordion title="invoice.*: Fiscal" icon="file-invoice">
    Agregado `invoice`. Veja [Fiscal](/docs/conceitos/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.           |
  </Accordion>

  <Accordion title="reprocess.*: Reprocessamento" icon="rotate">
    Agregados `reprocess_job` e `commission`. Veja [Reprocessamento](/docs/conceitos/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.                                            |
  </Accordion>

  <Accordion title="settings.*: Configurações" icon="gear">
    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`). |
  </Accordion>

  <Accordion title="webhook_endpoint.*: Webhooks de saída" icon="webhook">
    Agregado `webhook_endpoint`. Secrets aparecem **mascarados** (`rwhs_***1234`) nos payloads. Veja [Visão geral](/docs/webhooks/visao-geral) e [Assinatura](/docs/webhooks/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`. |
  </Accordion>

  <Accordion title="reconciliation.*: Reconciliação de dados" icon="scale-balanced">
    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](/docs/conceitos/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`.                                                                                                                                  |
  </Accordion>
</AccordionGroup>

## 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`. |

<Note>
  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"`.
</Note>

## Consumindo o catálogo

Há duas formas de consumir esses eventos:

<CardGroup cols={2}>
  <Card title="Pull: GET /events" icon="list" href="/docs/conceitos/event-store">
    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.
  </Card>

  <Card title="Push: Webhooks" icon="webhook" href="/docs/webhooks/visao-geral">
    Assine um subconjunto da taxonomia por endpoint e receba os eventos por HTTP, com assinatura HMAC e retries.
  </Card>
</CardGroup>

### Filtrando o log por tipo

```bash cURL theme={null}
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](/docs/convencoes/paginacao) e [Event store](/docs/conceitos/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`.

```bash cURL theme={null}
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

<CardGroup cols={2}>
  <Card title="Assinatura HMAC" icon="signature" href="/docs/webhooks/assinatura">
    Como verificar o header `Repass-Signature` e proteger seus endpoints contra replay.
  </Card>

  <Card title="Retries e dead letter" icon="rotate-right" href="/docs/webhooks/retries-e-dead-letter">
    Cronograma de tentativas, auto-disable e replay manual de entregas.
  </Card>

  <Card title="Event store" icon="database" href="/docs/conceitos/event-store">
    O log imutável de eventos como recurso de API: filtros, cursor e auditoria.
  </Card>

  <Card title="Conversões server-to-server" icon="server" href="/docs/guias/conversoes-server-to-server">
    Gere `conversion.created` e seus eventos de comissão a partir do seu backend.
  </Card>
</CardGroup>