Convenções de eventos

Nomenclatura, deduplicação e versionamento para eventos Stripe.

reference • updated 2026-03-15

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
Pedido mutável	`Idempotency-Key`	prevenir dupla execução em retries

Regras de versionamento

Alterações incompatíveis exigem nova versão de schema/evento.
Campos novos devem ser opcionais por defeito.
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": {}
}