Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(security): list webhook custom headers as plaintext credentials

Yudhi Armyndharis178f7deb3b08
diff --git a/docs/04-security-design.md b/docs/04-security-design.md
index 004e1801a..398d696c5 100644
--- a/docs/04-security-design.md
+++ b/docs/04-security-design.md
@@ -183,16 +183,16 @@ OpenWA serves plain HTTP on its port; terminate **TLS at your reverse proxy / lo
> **There is currently no application-level encryption at rest.** API keys are stored **hashed** (one-way) in the database, but the first-boot key file and other sensitive values are stored as plaintext in the database / on disk and are protected by filesystem and database permissions, not by encryption. Encryption at rest for these fields is a roadmap item, not a shipped feature — do not assume it.
-| Data | At rest | How it is protected |
-| ------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| API keys | **Hashed** — SHA-256 with an optional `API_KEY_PEPPER` HMAC; never reversible | A database leak alone cannot recover the keys; with a pepper set, hashes can't be precomputed offline. See §4.2. |
-| Session auth state (WhatsApp credentials) | Plaintext on disk (the engine's auth store under the data volume) | Filesystem permissions on the data volume — keep it private. |
-| Webhook secrets | Plaintext — `webhooks.secret` (`varchar`) | Database access control; never returned by the webhook read DTOs (write-only) and omitted from `GET /api/infra/export-data` webhook rows. |
-| Proxy credentials | Plaintext — `sessions.proxyUrl` may embed `user:pass` | Database access control; never returned by the session read DTOs — only masked `proxyHost`, `proxyType` (derived from the URL scheme), and `hasCredentials` on `GET/PATCH /proxy`. The userinfo is also stripped from `GET /api/infra/export-data` session rows; scheme and host survive so a restore cannot silently connect direct. |
-| Bootstrap admin key file (`data/.api-key`, or `BOOTSTRAP_KEY_FILE`) | Plaintext raw ADMIN key, written `0600` on first boot | Owner-only file permissions; removed when the key it holds is revoked or deleted. Delete it once the key is stored elsewhere. |
-| Plugin instance secrets | Plaintext: `plugin_instances.secret`, `verifyToken`, `config` | Database access control; `secret`, `verifyToken` and the config fields a plugin marks secret are masked on API reads, but `GET /api/infra/export-data` includes all three verbatim, so treat an export file as a secret. |
-| Generated config (`data/.env.generated`) | Plaintext file, written `0600` | Owner-only file permissions. |
-| Message content | Plaintext in the `messages` table | Database access control. |
+| Data | At rest | How it is protected |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| API keys | **Hashed** — SHA-256 with an optional `API_KEY_PEPPER` HMAC; never reversible | A database leak alone cannot recover the keys; with a pepper set, hashes can't be precomputed offline. See §4.2. |
+| Session auth state (WhatsApp credentials) | Plaintext on disk (the engine's auth store under the data volume) | Filesystem permissions on the data volume — keep it private. |
+| Webhook secrets and custom headers | Plaintext: `webhooks.secret` (`varchar`) and custom `webhooks.headers` (JSON, may carry receiver credentials) | Database access control; never returned by the webhook read DTOs (write-only) and omitted from `GET /api/infra/export-data` webhook rows. |
+| Proxy credentials | Plaintext — `sessions.proxyUrl` may embed `user:pass` | Database access control; never returned by the session read DTOs — only masked `proxyHost`, `proxyType` (derived from the URL scheme), and `hasCredentials` on `GET/PATCH /proxy`. The userinfo is also stripped from `GET /api/infra/export-data` session rows; scheme and host survive so a restore cannot silently connect direct. |
+| Bootstrap admin key file (`data/.api-key`, or `BOOTSTRAP_KEY_FILE`) | Plaintext raw ADMIN key, written `0600` on first boot | Owner-only file permissions; removed when the key it holds is revoked or deleted. Delete it once the key is stored elsewhere. |
+| Plugin instance secrets | Plaintext: `plugin_instances.secret`, `verifyToken`, `config` | Database access control; `secret`, `verifyToken` and the config fields a plugin marks secret are masked on API reads, but `GET /api/infra/export-data` includes all three verbatim, so treat an export file as a secret. |
+| Generated config (`data/.env.generated`) | Plaintext file, written `0600` | Owner-only file permissions. |
+| Message content | Plaintext in the `messages` table | Database access control. |
**Hardening you can apply today:** set `API_KEY_PEPPER`; restrict the data volume and database to the app's user; and encrypt at the infrastructure layer (LUKS / cloud-provider encrypted volumes / an encrypted managed Postgres) rather than relying on application-level field encryption, which is not implemented.
@@ -562,16 +562,16 @@ flowchart TB
### Secrets Inventory
-| Secret | Storage | Rotation guidance |
-| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| Database credentials | Environment variable | 90 days |
-| Redis password | Environment variable | 90 days |
-| API master key (`API_MASTER_KEY`) | Environment variable (first-boot seed only) | Not via the env var; see the note below |
-| API key pepper (`API_KEY_PEPPER`) | Environment variable | Rotating it invalidates all existing key hashes |
-| Webhook secrets | Database — **plaintext**; not in the webhook read DTOs, and omitted from `GET /api/infra/export-data` webhook rows | Per webhook |
-| Bootstrap admin key file (`data/.api-key`, or `BOOTSTRAP_KEY_FILE`) | File system: raw ADMIN key in **plaintext**, `0600`; removed when that key is revoked or deleted | Delete it once the key is stored elsewhere |
-| Plugin instance secrets (`plugin_instances.secret`, `verifyToken`, `config`) | Database: **plaintext**; `secret`, `verifyToken` and secret-marked config are masked on API reads, but `GET /api/infra/export-data` includes them verbatim | Per instance (regenerate-secret) |
-| Session auth state | File system (data volume) — **not encrypted** | Never (tied to the WA session) |
+| Secret | Storage | Rotation guidance |
+| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| Database credentials | Environment variable | 90 days |
+| Redis password | Environment variable | 90 days |
+| API master key (`API_MASTER_KEY`) | Environment variable (first-boot seed only) | Not via the env var; see the note below |
+| API key pepper (`API_KEY_PEPPER`) | Environment variable | Rotating it invalidates all existing key hashes |
+| Webhook secrets and custom headers (`webhooks.secret`, `headers`) | Database: **plaintext** (custom headers may carry receiver credentials); not in the webhook read DTOs, and omitted from `GET /api/infra/export-data` webhook rows | Per webhook |
+| Bootstrap admin key file (`data/.api-key`, or `BOOTSTRAP_KEY_FILE`) | File system: raw ADMIN key in **plaintext**, `0600`; removed when that key is revoked or deleted | Delete it once the key is stored elsewhere |
+| Plugin instance secrets (`plugin_instances.secret`, `verifyToken`, `config`) | Database: **plaintext**; `secret`, `verifyToken` and secret-marked config are masked on API reads, but `GET /api/infra/export-data` includes them verbatim | Per instance (regenerate-secret) |
+| Session auth state | File system (data volume) — **not encrypted** | Never (tied to the WA session) |
> `API_MASTER_KEY` only seeds the first ADMIN key, and is read only while the key table is empty. Changing it later has no effect: the new value never authenticates and the seeded key stays valid. Rotate by minting a new ADMIN key with `POST /api/auth/api-keys` and revoking the seeded `Default Admin Key`.