# Event taxonomy

Every event you emit maps to a canonical AO event type:

- **Format**: `<namespace>:<subkind>` matching
  `^[a-z][a-z0-9_-]*[:.][a-z][a-z0-9_-]+$` — e.g.
  `acme:deploy_failed`, `acme:incident_opened`. Use your product
  name as the namespace.
- **Mapping**: each manifest `events[]` entry declares `canonical`
  (the AO name), `provider_event` (your native event name — header
  value or payload type field), optionally `action_field` (a dot-path
  into the payload that disambiguates sub-actions), and
  `id_strategy`.
- **Id strategy**: how AO dedupes deliveries. Best: a per-delivery UUID
  header or payload field (`delivery_uuid`). Acceptable: a stable
  natural id (commit SHA, alert correlation id). Last resort:
  `synthesize` (AO hashes the payload — only when you truly have no
  id).

Samples: include one REAL payload per event type (sanitized of
customer data). If you sign webhooks, include one signed sample —
body + signature header value + the secret used — so we can verify our
implementation against yours. Samples become permanent test fixtures
on our side; treat them as part of your API contract.