Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(audit): list what the log records and that error is reserved

Yudhi Armyndhariscdac70111ab4
diff --git a/README.md b/README.md
index ac6a47815..b9f36082f 100644
--- a/README.md
+++ b/README.md
@@ -157,7 +157,7 @@ For any deployment where ethical, legal, or regulatory compliance matters (healt
| Rate Limiting | ✅ | Configurable request limits |
| CIDR Whitelisting | ✅ | IP-based access control |
| Chat Scoping | ✅ | Per-key `allowedChats` allowlist (groups and contacts): a key reaches only those chats, and routes not marked safe for it refuse it |
-| Audit Logging | ✅ | Audit trail for API-key, session, integration-instance, and infra admin operations (message sends and webhook deliveries are tracked in their own tables, not the audit log) |
+| Audit Logging | ✅ | Audit trail for API-key, session, integration-instance, plugin and infra admin operations (message sends and webhook deliveries have tables of their own, not the audit log) |
### Infrastructure
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index 4c2d10bf8..a4ab1b5ee 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -607,7 +607,7 @@ CREATE UNIQUE INDEX "IDX_api_keys_keyHash" ON api_keys("keyHash");
### 5.3.6 audit_logs
-Consolidated audit trail for API-key, session, send-pacing, rate-limit, queue-dashboard, integration-instance and infrastructure events. This is the **only** audit table — there are no separate `session_logs`, `webhook_logs`, or `api_key_logs` tables. Lives on the **main** (always-SQLite) connection.
+Consolidated audit trail for API-key, session, send-pacing, rate-limit, queue-dashboard, integration-instance, plugin-management and infrastructure events. This is the **only** audit table — there are no separate `session_logs`, `webhook_logs`, or `api_key_logs` tables. Lives on the **main** (always-SQLite) connection.
```sql
CREATE TABLE audit_logs (
@@ -667,7 +667,7 @@ id, version, the host of the requested download URL and config field names, neve
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.
+authoritative list, with the reason for each. The `error` severity is reserved too: nothing writes it, so every row carries `info` or `warn`, and `GET /api/audit?severity=error` returns zero rows.
> [!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 434272db3..1ff2aad74 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -5424,7 +5424,7 @@ 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 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).
+List audit-log entries, newest first. API-key lifecycle changes, session lifecycle events, send-pacing and rate-limit enforcement, queue-dashboard mutations, webhook delivery redrives, integration-instance changes, plugin management (install, update, uninstall, enable, disable, configuration, session activation) 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
@@ -5433,11 +5433,11 @@ List audit-log entries, newest first. API-key lifecycle changes, session lifecyc
| 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`. |
+| `severity` | `'info' \| 'warn' \| 'error'` | No | — | Filter by `AuditSeverity`. `error` is reserved and nothing writes it (rows are `info` or `warn`), so that filter returns zero rows. |
| `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`. |
+| `offset` | integer | No | `0` | Rows to skip; a negative value resolves to `0`, and a value above `9007199254740991` is capped at it, which returns an empty page. |
**Response** `200`
diff --git a/openapi.json b/openapi.json
index 367fec9e9..71e4baeae 100644
--- a/openapi.json
+++ b/openapi.json
@@ -41,6 +41,7 @@
"name": "severity",
"required": false,
"in": "query",
+ "description": "`error` is reserved: nothing writes it, so that filter returns no rows.",
"schema": {
"enum": [
"info",
diff --git a/src/modules/audit/audit.controller.ts b/src/modules/audit/audit.controller.ts
index 635b2e55f..40b1719b1 100644
--- a/src/modules/audit/audit.controller.ts
+++ b/src/modules/audit/audit.controller.ts
@@ -15,7 +15,12 @@ export class AuditController {
@RequireRole(ApiKeyRole.ADMIN)
@ApiOperation({ summary: 'List audit logs with optional filters' })
@ApiQuery({ name: 'action', required: false, enum: AuditAction })
- @ApiQuery({ name: 'severity', required: false, enum: AuditSeverity })
+ @ApiQuery({
+ name: 'severity',
+ required: false,
+ enum: AuditSeverity,
+ description: '`error` is reserved: nothing writes it, so that filter returns no rows.',
+ })
@ApiQuery({ name: 'sessionId', required: false })
@ApiQuery({ name: 'apiKeyId', required: false })
@ApiQuery({ name: 'limit', required: false, type: Number })