Convención de nombres

Usa <dominio>.<recurso>.<acción> para eventos públicos.
Evita verbos ambiguos (updated) sin contexto de negocio.
Mantén nombres estables para reducir roturas en consumidores.

Claves y deduplicación

Tipo	Campo recomendado	Objetivo
Evento técnico	`event.id`	deduplicar reentregas del provider
Operación de negocio	`checkout.session.id` o id funcional equivalente	asegurar unicidad lógica
Petición mutable	`Idempotency-Key`	prevenir doble ejecución en retries

Reglas de versionado

Cambios incompatibles requieren nueva versión de schema/evento.
Campos nuevos deben ser opcionales por defecto.
Deprecaciones deben incluir ventana explícita en 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": {}
}