## 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 |
| Trabajo asíncrono Beacon | `webhookEventId` o `queueJobId` | correlacionar replay y conciliación sin duplicar efectos |

## Reglas de versionado

1. Cambios incompatibles requieren nueva versión de schema/evento.
2. Campos nuevos deben ser opcionales por defecto.
3. 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": {}
}
```

<Note title="Buena práctica">Trata el contrato de eventos como producto: schema versionado, ownership explícito y pruebas de regresión en consumidores.</Note>