## Convenção de nomes

- Usa `<domínio>.<recurso>.<ação>` para eventos públicos.
- Evita termos ambíguos (`updated`) sem contexto de negócio.
- Mantém nomes estáveis para reduzir breaking changes no consumidor.

## Chaves e deduplicação

| Tipo | Campo recomendado | Objetivo |
| --- | --- | --- |
| Evento técnico | `event.id` | deduplicar reentregas do provider |
| Operação de negócio | `checkout.session.id` ou id funcional equivalente | garantir unicidade lógica |
| Trabalho assíncrono Beacon | `webhookEventId` ou `queueJobId` | correlacionar replay e reconciliação sem duplicar efeitos |

## Regras de versionamento

1. Alterações incompatíveis exigem nova versão de schema/evento.
2. Campos novos devem ser opcionais por defeito.
3. Depreciações devem ter janela e comunicação explícitas no changelog.

## Envelope mínimo recomendado

```json
{
  "event_id": "evt_123",
  "event_type": "billing.checkout.completed",
  "occurred_at": "2026-03-15T12:00:00Z",
  "organization_id": "org_123",
  "payload": {}
}
```

<Note title="Boa prática">Define contrato de evento como produto: schema versionado, ownership claro e testes de regressão no consumer.</Note>