Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(audit): list all eight audit actions that are never emitted

Yudhi Armyndharis4c560414a295
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index d2813f3b5..279f5c584 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -614,6 +614,11 @@ plugin instances (`integration_instance_created`, `integration_instance_updated`
`infra_restart_requested`, `infra_data_exported`, `infra_data_imported`, `infra_storage_exported`,
`infra_storage_imported`).
+Eight of these are reserved and never emitted, so no row ever carries them: `api_key_used`,
+`session_connected`, `message_sent`, `message_failed`, `webhook_created`, `webhook_deleted`,
+`webhook_triggered` and `webhook_failed`. `src/modules/audit/intentionally-unemitted-actions.ts` is the
+authoritative list, with the reason for each.
+
> [!NOTE]
> Audit-log retention is automatic: see [§5.7 Data Retention](#57-data-retention). Other event types (session logs, API access logs) are surfaced via structured application logging, not dedicated database tables. The one exception is a webhook delivery that exhausts every retry — that lands in the `webhook_delivery_failures` table (§5.3.8), not just the log stream.
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index f90b5274f..151d9c787 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -5237,20 +5237,20 @@ Notes: raw return of an in-memory `Settings` object built once in the controller
#### GET /api/audit
-List audit-log entries, newest first. API-key lifecycle changes, session lifecycle events and ADMIN infra operations land here. **The six actions below are never emitted**: message sends and webhook deliveries are tracked in their own tables (`messages`, `webhook_delivery_failures`) — `webhook_created`/`webhook_deleted` are simply not wired yet — so filtering for `message_sent`, `message_failed`, `webhook_created`, `webhook_deleted`, `webhook_triggered` or `webhook_failed` returns zero rows by design.
+List audit-log entries, newest first. API-key lifecycle changes, session lifecycle events and ADMIN infra operations land here. **The eight actions below are never emitted**, so filtering for any of them returns zero rows by design: `message_sent` and `message_failed` (every send and its outcome is in the `messages` table), `webhook_triggered` and `webhook_failed` (tracked in `webhook_delivery_failures` and the `openwa_webhook_delivery_failures_total` counter), `webhook_created` and `webhook_deleted` (not wired yet), `api_key_used` (it would fire on every authenticated request; failed authentication is audited as `api_key_auth_failed`), and `session_connected` (an engine-level transition already reflected in `sessions.status`; the user-initiated `session_started` and `session_stopped` are audited).
**Auth:** API key (ADMIN) · **Scope:** rows are confined to the calling key's `allowedSessions` — the `sessionId` query may only narrow within that list, never widen it
**Query parameters**
-| Name | Type | Required | Default | Description |
-| ----------- | ----------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `action` | string | No | — | Filter by `AuditAction` (e.g. `api_key_created`, `session_started`, `infra_data_imported`). Message/webhook actions are never emitted (see above). |
-| `severity` | `'info' \| 'warn' \| 'error'` | No | — | Filter by `AuditSeverity`. |
-| `sessionId` | string | No | — | Narrow to one session. A value outside the key's `allowedSessions` returns `{ "data": [], "total": 0 }`. |
-| `apiKeyId` | string | No | — | Filter by the acting key's id. |
-| `limit` | integer | No | `50` | Page size, clamped to a maximum of `200`. |
-| `offset` | integer | No | `0` | Rows to skip; a negative value resolves to `0`. |
+| Name | Type | Required | Default | Description |
+| ----------- | ----------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `action` | string | No | — | Filter by `AuditAction` (e.g. `api_key_created`, `session_started`, `infra_data_imported`). Message, webhook, `api_key_used` and `session_connected` actions are never emitted (see above). |
+| `severity` | `'info' \| 'warn' \| 'error'` | No | — | Filter by `AuditSeverity`. |
+| `sessionId` | string | No | — | Narrow to one session. A value outside the key's `allowedSessions` returns `{ "data": [], "total": 0 }`. |
+| `apiKeyId` | string | No | — | Filter by the acting key's id. |
+| `limit` | integer | No | `50` | Page size, clamped to a maximum of `200`. |
+| `offset` | integer | No | `0` | Rows to skip; a negative value resolves to `0`. |
**Response** `200`
diff --git a/src/modules/audit/audit-coverage.spec.ts b/src/modules/audit/audit-coverage.spec.ts
index c6cf9001e..177f3fbe8 100644
--- a/src/modules/audit/audit-coverage.spec.ts
+++ b/src/modules/audit/audit-coverage.spec.ts
@@ -57,6 +57,16 @@ describe('audit action emit coverage', () => {
expect(stale).toEqual([]);
});
+ // Filtering GET /api/audit for an unemitted action silently returns nothing, so the API docs must
+ // name every one of them.
+ it('docs/06 names every intentionally-unemitted action in the GET /api/audit description', () => {
+ const docs = readFileSync(join(SRC_DIR, '..', 'docs', '06-api-specification.md'), 'utf8');
+ const paragraph = docs.split('\n').find(line => line.startsWith('List audit-log entries, newest first.')) ?? '';
+ const missing = Object.keys(INTENTIONALLY_UNEMITTED_ACTIONS).filter(value => !paragraph.includes(`\`${value}\``));
+ expect(paragraph).not.toBe('');
+ expect(missing).toEqual([]);
+ });
+
it('intentionally-unemitted registry entries each carry a non-empty reason', () => {
const empties = Object.entries(INTENTIONALLY_UNEMITTED_ACTIONS)
.filter(([, reason]) => typeof reason !== 'string' || reason.trim().length === 0)