## Naming convention

- Use `<domain>.<resource>.<action>` for public event names.
- Avoid ambiguous verbs (`updated`) without business context.
- Keep event names stable to reduce consumer breakage.

## Keys and deduplication

| Type | Recommended field | Purpose |
| --- | --- | --- |
| Technical event | `event.id` | dedupe provider re-deliveries |
| Business operation | `checkout.session.id` (or equivalent functional id) | enforce logical uniqueness |
| Beacon async work | `webhookEventId` or `queueJobId` | correlate replay and reconciliation without duplicating effects |

## Versioning rules

1. Breaking changes require a new schema/event version.
2. New fields should be optional by default.
3. Deprecations should include an explicit communication window in changelog.

## Recommended minimum envelope

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

<Note title="Good practice">Treat event contracts as products: versioned schema, explicit ownership, and consumer regression tests.</Note>