Audit Logging & Monitoring

Audit Log Architecture

Switchbord maintains an audit_logs table that records security-relevant operations performed within each workspace. The audit trail is designed to answer: who did what, to which object, in which workspace, and when.

Schema

CREATE TABLE audit_logs (
  id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  workspace_id  uuid NOT NULL REFERENCES workspaces(id),
  actor_user_id uuid REFERENCES auth.users(id),  -- null for system-initiated actions
  entity_type   text NOT NULL,  -- e.g. 'contact', 'workspace_member', 'api_key', 'secret'
  entity_id     text NOT NULL,  -- ID of the affected entity
  action        text NOT NULL,  -- e.g. 'gdpr_erasure', 'member_removed', 'secret_updated'
  metadata      jsonb,          -- action-specific context (sanitized, no PII values)
  created_at    timestamptz NOT NULL DEFAULT now()
);

All audit log queries are filtered by workspace_id, ensuring workspace isolation extends to the audit trail itself.

What Is Logged

Currently Implemented

Event	Entity Type	Action	Triggered By
Workspace member removed	`workspace_member`	`member_removed`	Admin/owner removing a member
GDPR erasure requested	`contact`	`gdpr_erasure`	Erasure endpoint `DELETE /api/contacts/[id]/gdpr`
GDPR data export	`contact`	`gdpr_export`	Export endpoint `GET /api/contacts/[id]/gdpr`
Secret created/updated	`secret`	`secret_updated`	Workspace admin updating Vault secret
Secret validation failure	`secret`	`secret_validation_failed`	Invalid or malformed secret rejected on write
API key created	`api_key`	`api_key_created`	Developer creating a new API key
API key revoked	`api_key`	`api_key_revoked`	Developer/admin revoking a key
Channel settings updated	`channel_settings`	`channel_settings_updated`	Workspace admin modifying WhatsApp channel config
Consent event (opt-in)	`consent`	`consent_opt_in`	Contact opts in via WhatsApp
Consent event (opt-out)	`consent`	`consent_opt_out`	Contact opts out via WhatsApp
Account alert triggered	`account_alert`	`alert_triggered`	System detecting threshold breach or anomaly (BORD-189)

Writing an Audit Log Entry

await writeAuditLog({
  workspaceId: string,
  actorUserId: string | null,
  entityType: 'contact' | 'workspace_member' | 'api_key' | 'secret' | 'channel_settings' | 'consent' | 'account_alert',
  entityId: string,
  action: string,
  metadata?: Record<string, unknown>, // never include raw PII values
});

Audit log entries are written synchronously within the same database transaction as the operation they record where possible. This ensures the audit trail reflects actual operations, not just attempted ones.

Planned Audit Log Enhancements

Read-Access Logging (BORD-168)

Currently, only write operations (mutations, deletions) are logged. Planned work includes logging read access to PII tables — specifically tracking which users accessed which contact records and when. This is required for full HIPAA §164.312(b) compliance.

Tamper-Evident Hash Chain (BORD-168)

Each audit log entry will include a cryptographic hash of the previous entry in the workspace’s log chain. This creates a tamper-evident structure where modification of any past entry invalidates all subsequent hashes. Planned implementation uses SHA-256 chaining.

entry_n.hash = SHA256(entry_(n-1).hash || entry_n.data)

Immutable Export to Object Storage (BORD-168)

Audit logs will be periodically exported to write-once object storage (e.g., Supabase Storage with immutable bucket policy) to provide a backup that cannot be modified even by database administrators.

Observability Stack

Error Monitoring: Sentry

Switchbord integrates with Sentry for real-time error monitoring across all application surfaces. Sentry captures:

Unhandled exceptions in API routes
Worker job failures
Frontend JavaScript errors

Error reports are scrubbed to avoid capturing PII in stack traces. Configured via packages/observability.

Log Aggregation: Better Stack

Application logs from Vercel and Railway are aggregated in Better Stack (formerly Logtail). Structured logs include request IDs for correlation across services.

Health Monitoring

The /api/health and /api/ready endpoints are publicly accessible and monitored by uptime services to detect availability degradation.

Account Alerts (BORD-189)

Switchbord ships real-time account-level alerts that surface operational and security-relevant events to workspace operators:

WhatsApp API health alerts — notifications when the Meta API returns elevated error rates, rate-limit responses, or webhook delivery failures for a workspace’s phone numbers
Secret expiry alerts — warnings when Vault-stored tokens or API keys are approaching expiration
Consent threshold alerts — notifications when a workspace’s opt-out rate exceeds a configurable threshold, indicating potential compliance risk
Usage anomaly alerts — flags for unusual message volume spikes, bulk contact operations, or API key usage patterns

Alerts are delivered via the in-app notification feed and can be forwarded to Slack or webhook endpoints. All alert events are recorded in the audit_logs table under the account_alert entity type.

Planned: Security Incident Detection (BORD-166)

The following capabilities are planned as part of BORD-166:

Anomaly detection: Flag unusual patterns such as bulk contact exports, high API key usage volume, or access from unexpected IP ranges
Security event monitoring: Dedicated alerting for security-relevant events (failed auth bursts, concurrent session anomalies, privilege escalation attempts)
Alerting integration: Webhook-based alerts to Slack, PagerDuty, or operator-configured endpoints

Planned: Breach Notification Workflow (BORD-166)

GDPR Art.33 requires notification to the supervisory authority within 72 hours of becoming aware of a personal data breach. Art.34 may require notification to affected data subjects. Planned capabilities to support this obligation:

Incident detection triggers that create an incident record with timestamp of detection
Breach assessment workflow — guided questions to determine notification scope
Notification draft generation — pre-populated templates for DPA submission
72-hour countdown timer — visible in the admin UI once an incident is declared
Affected workspace and contact scoping — identify which contacts’ data may have been involved

The 72-hour breach notification workflow is currently planned (BORD-166). Organizations with immediate compliance requirements should establish a manual incident response procedure until this capability is implemented.

Retention of Audit Logs

Audit logs are retained for the workspace’s configured data_retention_days period, with a minimum retention of 365 days regardless of the workspace setting. This ensures that audit trails remain available for post-incident investigation and compliance audits. GDPR erasure requests do not delete audit log entries. Entries recording the fact of an erasure are themselves retained as evidence of compliance.

Compliance Mapping

Standard	Control	Implementation
ISO 27001	A.12.4.1 — Event logging	`audit_logs` table for write operations (shipped BORD-158)
ISO 27001	A.12.4.2 — Protection of log information	Workspace-scoped, admin-read-only (tamper-evident chain planned)
ISO 27001	A.12.4.3 — Administrator and operator logs	Member removal, secret changes, channel settings, consent events logged
HIPAA	§164.312(b) — Audit controls	Write-operation audit trail; read-access logging planned BORD-168
GDPR	Art.33 — Breach notification to supervisory authority	72h workflow planned BORD-166
GDPR	Art.34 — Breach notification to data subjects	Scope assessment planned BORD-166
SOC 2	CC7.1 — System monitoring	Sentry, Better Stack, health endpoints, account alerts (BORD-189)
SOC 2	CC7.2 — Anomalous activity evaluation	Anomaly detection planned BORD-166

For the full compliance control mapping, see the Compliance Matrix.

Get Started

Features

WhatsApp

Guides

Contributing

Platform

Operations

Security & Compliance

Audit Logging & Monitoring

Audit Log Architecture

Schema

What Is Logged

Currently Implemented

Writing an Audit Log Entry

Planned Audit Log Enhancements

Read-Access Logging (BORD-168)

Tamper-Evident Hash Chain (BORD-168)

Immutable Export to Object Storage (BORD-168)

Observability Stack

Error Monitoring: Sentry

Log Aggregation: Better Stack

Health Monitoring

Account Alerts (BORD-189)

Planned: Security Incident Detection (BORD-166)

Planned: Breach Notification Workflow (BORD-166)

Retention of Audit Logs

Compliance Mapping

​Audit Log Architecture

​Schema

​What Is Logged

​Currently Implemented

​Writing an Audit Log Entry

​Planned Audit Log Enhancements

​Read-Access Logging (BORD-168)

​Tamper-Evident Hash Chain (BORD-168)

​Immutable Export to Object Storage (BORD-168)

​Observability Stack

​Error Monitoring: Sentry

​Log Aggregation: Better Stack

​Health Monitoring

​Account Alerts (BORD-189)

​Planned: Security Incident Detection (BORD-166)

​Planned: Breach Notification Workflow (BORD-166)

​Retention of Audit Logs

​Compliance Mapping

Audit Log Architecture

Schema

What Is Logged

Currently Implemented

Writing an Audit Log Entry

Planned Audit Log Enhancements

Read-Access Logging (BORD-168)

Tamper-Evident Hash Chain (BORD-168)

Immutable Export to Object Storage (BORD-168)

Observability Stack

Error Monitoring: Sentry

Log Aggregation: Better Stack

Health Monitoring

Account Alerts (BORD-189)

Planned: Security Incident Detection (BORD-166)

Planned: Breach Notification Workflow (BORD-166)

Retention of Audit Logs

Compliance Mapping