Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(webhook): refuse custom header values outside Latin-1

Yudhi Armyndharisffa8079dd2d2
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 90c4e788e..bd05093b5 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -4619,7 +4619,7 @@ Create a webhook for the session.
| url | string | yes | `@IsUrl({ require_tld: false })` (allows hostnames without a dot, e.g. `http://localhost:3000`); also run through the SSRF guard, which can reject with `400`. Entity column max 2048 chars. | Webhook URL to receive events. |
| events | string[] | no | `@IsArray`, `@ArrayMinSize(1)`, `@IsIn([...WEBHOOK_EVENTS, '*'], { each: true })` | Event names to subscribe to (see allowed set above). Defaults to `["message.received"]` when omitted. |
| secret | string | no | `@IsString`, `@MinLength(16)`, `@MaxLength(255)` | HMAC-SHA256 signing key. **Write-only** — never returned by a webhook route (not returned by `GET /api/infra/export-data` either). Used for `X-OpenWA-Signature`. Defaults to `null`. |
-| headers | Record<string,string> | no | `@IsHeaderMap()` — flat object (not array), ≤50 entries, names match `/^[A-Za-z0-9-]+$/`, values are strings ≤1024 chars with no C0 control/DEL (CR/LF injection guard). | Custom headers added to deliveries. **Write-only** — never returned by a webhook route (not returned by `GET /api/infra/export-data` either). At delivery, `content-type` and `x-openwa-*` names are stripped, and so are the connection-level names the HTTP client owns: `connection`, `content-length`, `expect`, `keep-alive`, `te`, `trailer`, `transfer-encoding` and `upgrade`. Defaults to `{}`. |
+| headers | Record<string,string> | no | `@IsHeaderMap()`: flat object (not array), ≤50 entries, names match `/^[A-Za-z0-9-]+$/`, values are strings ≤1024 chars with no C0 control/DEL (CR/LF injection guard) and nothing above U+00FF (Latin-1 only). | Custom headers added to deliveries. **Write-only** — never returned by a webhook route (not returned by `GET /api/infra/export-data` either). At delivery, `content-type` and `x-openwa-*` names are stripped, and so are the connection-level names the HTTP client owns: `connection`, `content-length`, `expect`, `keep-alive`, `te`, `trailer`, `transfer-encoding` and `upgrade`. Defaults to `{}`. |
| filters | WebhookFilters \| null | no | `@IsValidWebhookFilters()`, i.e. `{ conditions: [...] }`; each condition `{ field, operator('is'\|'isNot'\|'contains'\|'equals'), value(string\|string[]\|boolean), caseSensitive?:boolean }`; bounds: max 20 conditions, 100 values/condition, 1000-char text values. Message fields: `sender`, `recipient`, `chatId`, `body`, `type`, `isGroup`, `kind`, `fromMe`, `hasMedia`, `mentions`. An id-valued condition accepts a bare phone number, but a group must be written as its full `<id>@g.us` JID: bare digits canonicalise to `@c.us` and match no group. | Optional AND pre-filter; **all** conditions must match for the webhook to fire. Omit/null = fire on every subscribed event. Defaults to `null`. ⚠️ A condition whose field is DEFINED for the event family but absent from that event's payload does not scope the event, it decides it outright: an `is`, `contains` or `equals` condition cannot match and suppresses the event, while an `isNot` condition passes it, and so does a boolean field compared with `false`, because an absent boolean reads as `false` (a field with no definition for the family is skipped instead). `message.ack`/`message.failed` carry `{ id, messageId, status, ack }` and `message.reaction` carries `{ messageId, chatId, reaction, senderId }`, none of which has a sender or body, so a `sender` `is` filter silently drops all three and a `sender` `isNot` filter delivers all three. `message.ack`/`message.failed` carry no `chatId` either, so a `chatId` `isNot` exclusion does not keep that chat's acks and failures out. Scope the subscription with `events[]` rather than relying on a filter to be inert. Set `LOG_LEVEL=debug` to see each suppression and the payload fields that were available. |
| retryCount | number (int) | no | `@IsInt`, `@Min(0)`, `@Max(5)` | Total delivery attempts per event, including the first: `0` and `1` both mean a single attempt with no retry. An event that exhausts them is recorded in `GET /api/webhooks/delivery-failures`; the webhook stays active. Defaults to `3`. |
diff --git a/src/modules/webhook/dto/is-header-map.validator.ts b/src/modules/webhook/dto/is-header-map.validator.ts
index 484152df6..b5946e61f 100644
--- a/src/modules/webhook/dto/is-header-map.validator.ts
+++ b/src/modules/webhook/dto/is-header-map.validator.ts
@@ -4,11 +4,15 @@ const HEADER_NAME = /^[A-Za-z0-9-]+$/;
const MAX_HEADERS = 50;
const MAX_VALUE_LENGTH = 1024;
-/** Reject C0 control chars + DEL — notably CR/LF, the header-injection vector. */
-function hasControlChar(s: string): boolean {
+/**
+ * Reject C0 control chars and DEL (notably CR/LF, the header-injection vector) and anything above
+ * U+00FF: the HTTP client sends header values as Latin-1 bytes and throws on any wider code unit,
+ * which would fail every delivery of the webhook.
+ */
+function hasInvalidValueChar(s: string): boolean {
for (let i = 0; i < s.length; i++) {
const c = s.charCodeAt(i);
- if (c < 0x20 || c === 0x7f) return true;
+ if (c < 0x20 || c === 0x7f || c > 0xff) return true;
}
return false;
}
@@ -16,8 +20,9 @@ function hasControlChar(s: string): boolean {
/**
* Validate operator-supplied webhook custom headers as a flat map of valid header names to string
* values: rejects non-object shapes, invalid header names, non-string or control-character values
- * (CR/LF header injection), and over-large maps (≤50 entries, value ≤1024 chars). Reserved-name
- * stripping still happens at delivery time (sanitizeCustomHeaders); this is the input-side guard.
+ * (CR/LF header injection), values outside Latin-1, and over-large maps (≤50 entries, value ≤1024
+ * chars). Reserved-name stripping still happens at delivery time (sanitizeCustomHeaders); this is the
+ * input-side guard.
*/
export function IsHeaderMap(options?: ValidationOptions) {
return function (target: object, propertyName: string): void {
@@ -34,11 +39,11 @@ export function IsHeaderMap(options?: ValidationOptions) {
if (entries.length > MAX_HEADERS) return false;
return entries.every(
([k, v]) =>
- HEADER_NAME.test(k) && typeof v === 'string' && v.length <= MAX_VALUE_LENGTH && !hasControlChar(v),
+ HEADER_NAME.test(k) && typeof v === 'string' && v.length <= MAX_VALUE_LENGTH && !hasInvalidValueChar(v),
);
},
defaultMessage(): string {
- return 'headers must be a flat map of valid header names to string values (no control characters, max 50 entries, value max 1024 chars)';
+ return 'headers must be a flat map of valid header names to string values (no control characters or characters outside Latin-1, max 50 entries, value max 1024 chars)';
},
},
});
diff --git a/src/modules/webhook/dto/webhook.dto.spec.ts b/src/modules/webhook/dto/webhook.dto.spec.ts
index 7c2679b60..d1ae9b1c6 100644
--- a/src/modules/webhook/dto/webhook.dto.spec.ts
+++ b/src/modules/webhook/dto/webhook.dto.spec.ts
@@ -91,6 +91,29 @@ describe('webhook DTO custom-header validation', () => {
const errs = await errorsFor(UpdateWebhookDto, { headers: { 'X-Evil': 'a\nb' } });
expect(errs.some(e => e.property === 'headers')).toBe(true);
});
+
+ // Header values go out as Latin-1 bytes; a wider code unit throws inside the HTTP client on every
+ // delivery, so it must be refused when the webhook is saved.
+ it.each(['Caf\u00e9 \u2192 Norte', '\u6771\u4eac', 'hi \u{1F600}'])(
+ 'rejects a header value outside Latin-1 (%s) on create and update',
+ async value => {
+ const create = await errorsFor(CreateWebhookDto, {
+ url: 'https://example.com/hook',
+ headers: { 'X-Tenant': value },
+ });
+ expect(create.some(e => e.property === 'headers')).toBe(true);
+ const update = await errorsFor(UpdateWebhookDto, { headers: { 'X-Tenant': value } });
+ expect(update.some(e => e.property === 'headers')).toBe(true);
+ },
+ );
+
+ it('accepts a Latin-1 header value on create and update', async () => {
+ const headers = { 'X-Tenant': 'Caf\u00e9 Norte \u00ff' };
+ const create = await errorsFor(CreateWebhookDto, { url: 'https://example.com/hook', headers });
+ expect(create.some(e => e.property === 'headers')).toBe(false);
+ const update = await errorsFor(UpdateWebhookDto, { headers });
+ expect(update.some(e => e.property === 'headers')).toBe(false);
+ });
});
describe('webhook DTO filter validation', () => {