Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(webhooks): correct what a filter on an absent field does

Yudhi Armyndharis6b0f0d198c34
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index d0345999a..443f2ac41 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -4586,14 +4586,14 @@ Create a webhook for the session.
**Request body** — `CreateWebhookDto`
-| Field | Type | Required | Constraints | Description |
-| ---------- | ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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. 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 cannot match, so it suppresses the event entirely (a field with no definition for the family is skipped instead, and does not suppress). `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` filter silently drops all three. 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`. |
+| Field | Type | Required | Constraints | Description |
+| ---------- | ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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. 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`. |
```json
{
diff --git a/src/modules/webhook/filters/filter-evaluator.spec.ts b/src/modules/webhook/filters/filter-evaluator.spec.ts
index 725267e21..4c33bc614 100644
--- a/src/modules/webhook/filters/filter-evaluator.spec.ts
+++ b/src/modules/webhook/filters/filter-evaluator.spec.ts
@@ -259,6 +259,11 @@ describe('evaluateFilters', () => {
// And the exclusion direction delivers them, for the same reason: the field is not there.
const deny = filters({ field: 'chatId', operator: 'isNot', value: ['[email protected]'] });
expect(evaluateFilters(deny, 'message.ack', ackPayload)).toBe(true);
+ expect(evaluateFilters(deny, 'message.failed', failedPayload)).toBe(true);
+ // An absent boolean reads as false, so `is false` passes both as well.
+ const notGroup = filters({ field: 'isGroup', operator: 'is', value: false });
+ expect(evaluateFilters(notGroup, 'message.ack', ackPayload)).toBe(true);
+ expect(evaluateFilters(notGroup, 'message.failed', failedPayload)).toBe(true);
});
it('scopes message.revoked / edited payloads that only carry chatId', () => {
diff --git a/src/modules/webhook/filters/filter-types.ts b/src/modules/webhook/filters/filter-types.ts
index 2346a49ca..09d5c1346 100644
--- a/src/modules/webhook/filters/filter-types.ts
+++ b/src/modules/webhook/filters/filter-types.ts
@@ -103,8 +103,9 @@ export const FILTER_FIELDS: Record<string, FieldDefinition[]> = {
// Conversation JID (DM or group). Carried by the message events proper: `IncomingMessage`
// declares `chatId` required, and the edited, reaction and revoked events set it explicitly.
// NOT by `message.ack` and `message.failed`, whose payload is `{ id, messageId, status, ack }`,
- // so a chatId condition suppresses those two entirely rather than scoping them; scope the
- // subscription with `events[]` instead (docs/06 carries the same warning for `sender`).
+ // so a chatId condition never scopes those two: an `is` condition suppresses every one of them
+ // and an `isNot` condition lets every one through. Scope the subscription with `events[]`
+ // instead (docs/06 carries the same warning for `sender`).
// Deliberately without a fall back to `from`, which is the sender on a DM and this session on
// an outbound message, so it would silently scope the filter to the wrong conversation.
field: 'chatId',
diff --git a/src/modules/webhook/webhook-delivery.service.ts b/src/modules/webhook/webhook-delivery.service.ts
index a3afb9a85..a19282f35 100644
--- a/src/modules/webhook/webhook-delivery.service.ts
+++ b/src/modules/webhook/webhook-delivery.service.ts
@@ -237,8 +237,9 @@ export class WebhookDeliveryService implements OnModuleInit, OnModuleDestroy {
// A subscribed webhook that a filter drops leaves no trace otherwise: dispatch() awaits an empty
// array and returns, and the delivery-failure table only records deliveries that were ATTEMPTED.
// That is fine when the filter is doing its job, and indistinguishable from it when it is not —
- // a condition on a field the event's payload does not carry resolves to undefined and fails,
- // which is how a `sender` filter silently swallows every message.ack. Debug rather than warn:
+ // an `is`/`contains`/`equals` condition on a field the event's payload does not carry resolves to
+ // undefined and fails, which is how a `sender is` filter silently swallows every message.ack
+ // (an `isNot` condition, or a boolean compared with false, passes instead). Debug rather than warn:
// suppression is the normal outcome of a working filter, so this is a trace to switch on while
// investigating, not an alarm.
if (matching.length < subscribed.length) {