Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(webhook): allow an empty filter condition list in the contract

Yudhi Armyndharis96cccdf96554
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 8c3dbfe6a..c1cd6d42d 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -4692,7 +4692,7 @@ Update a webhook. Partial — only fields present in the body are changed.
| events | string[] | no | `@IsOptional`, `@IsArray`, `@ArrayMinSize(1)`, `@IsIn([...WEBHOOK_EVENTS, '*'], { each: true })` | Same allowed set as create (incl. `*`). |
| secret | string | no | `@IsOptional`, `@IsString`, `@MinLength(16)` (skipped for `""`, which clears it), `@MaxLength(255)` | **Write-only.** An empty string is normalized to `null`, which disables HMAC. |
| headers | Record<string,string> | no | `@IsOptional`, `@IsHeaderMap()` (same constraints as create) | **Write-only.** Replaces existing headers wholesale when provided. |
-| filters | WebhookFilters \| null | no | `@IsOptional`, `@IsValidWebhookFilters()` | Set to `null` to clear filters. |
+| filters | WebhookFilters \| null | no | `@IsOptional`, `@IsValidWebhookFilters()` | Set to `null` or `{ conditions: [] }` to clear filters. |
| active | boolean | no | `@IsOptional`, `@IsBoolean` | Enable/disable the webhook. (Present only on update, not create.) |
| retryCount | number (int) | no | `@IsOptional`, `@IsInt`, `@Min(0)`, `@Max(5)` | Total delivery attempts per event, including the first. |
diff --git a/openapi.json b/openapi.json
index ed8ee71d6..284080e0c 100644
--- a/openapi.json
+++ b/openapi.json
@@ -11116,9 +11116,8 @@
"type": "object",
"properties": {
"conditions": {
- "minItems": 1,
"maxItems": 20,
- "description": "Every condition must match (AND) for the webhook to fire.",
+ "description": "Every condition must match (AND) for the webhook to fire. An empty list means no filter: the webhook fires on every subscribed event.",
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookFilterConditionDto"
diff --git a/sdk/java/README.md b/sdk/java/README.md
index 5f708d09b..08bceeb60 100644
--- a/sdk/java/README.md
+++ b/sdk/java/README.md
@@ -78,6 +78,10 @@ plus `client.auth()`.
Operator-only modules (`docker`, `metrics`, `infra`, `plugins`, `mcp`) are
intentionally not exposed; all user-facing resources are.
+`UpdateWebhookRequest` omits null fields, so `filters(null)` leaves a
+webhook's filters unchanged. To remove every filter, pass
+`new WebhookFilters(List.of())` instead.
+
## Error handling
Errors are a typed, unchecked hierarchy — branch with `instanceof` or on
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/UpdateWebhookRequest.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/UpdateWebhookRequest.java
index 2c3fa957e..38961e08b 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/UpdateWebhookRequest.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/UpdateWebhookRequest.java
@@ -53,6 +53,11 @@ public record UpdateWebhookRequest(
return this;
}
+ /**
+ * Replace the webhook's filters. To remove every filter, pass
+ * {@code new WebhookFilters(List.of())}; {@code filters(null)} leaves the existing filters
+ * unchanged, because a null field is omitted from the request.
+ */
public Builder filters(WebhookFilters v) {
this.filters = v;
return this;
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/resources/WebhooksResource.java b/sdk/java/src/main/java/com/rmyndharis/openwa/resources/WebhooksResource.java
index c214e5ef9..5fcec86dc 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/resources/WebhooksResource.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/resources/WebhooksResource.java
@@ -61,7 +61,10 @@ public final class WebhooksResource {
HttpMethod.POST, "/api/sessions/" + encodeSegment(sessionId) + "/webhooks", null, body, WebhookResponse.class);
}
- /** Update a webhook. */
+ /**
+ * Update a webhook. Fields left null are not sent and stay unchanged. To remove every filter,
+ * set {@code filters(new WebhookFilters(List.of()))}; {@code filters(null)} keeps the current ones.
+ */
public WebhookResponse update(String sessionId, String id, UpdateWebhookRequest body) {
return client.request(
HttpMethod.PUT,
diff --git a/sdk/java/src/test/java/com/rmyndharis/openwa/resources/WebhooksResourceTest.java b/sdk/java/src/test/java/com/rmyndharis/openwa/resources/WebhooksResourceTest.java
index 01194034b..1470a53f3 100644
--- a/sdk/java/src/test/java/com/rmyndharis/openwa/resources/WebhooksResourceTest.java
+++ b/sdk/java/src/test/java/com/rmyndharis/openwa/resources/WebhooksResourceTest.java
@@ -65,6 +65,18 @@ class WebhooksResourceTest {
assertTrue(tx.lastRequest().body().contains("\"active\":false"));
}
+ @Test
+ void updateClearsFiltersWithAnEmptyListAndLeavesThemOnNull() {
+ // The documented way to remove every filter: null fields are omitted, so filters(null)
+ // cannot clear them.
+ tx.respond(200, WEBHOOK_JSON);
+ client.webhooks.update("s", "w1", UpdateWebhookRequest.builder().filters(new WebhookFilters(List.of())).build());
+ assertEquals("{\"filters\":{\"conditions\":[]}}", tx.lastRequest().body());
+ tx.respond(200, WEBHOOK_JSON);
+ client.webhooks.update("s", "w1", UpdateWebhookRequest.builder().filters(null).build());
+ assertEquals("{}", tx.lastRequest().body());
+ }
+
@Test
void deleteHitsWebhookPath() {
tx.respond(204, "");
diff --git a/src/modules/webhook/dto/webhook.dto.ts b/src/modules/webhook/dto/webhook.dto.ts
index 14d76a72c..e4d8fc506 100644
--- a/src/modules/webhook/dto/webhook.dto.ts
+++ b/src/modules/webhook/dto/webhook.dto.ts
@@ -49,9 +49,9 @@ class WebhookFilterConditionDto {
class WebhookFiltersDto {
@ApiProperty({
type: [WebhookFilterConditionDto],
- minItems: 1,
maxItems: MAX_CONDITIONS,
- description: 'Every condition must match (AND) for the webhook to fire.',
+ description:
+ 'Every condition must match (AND) for the webhook to fire. An empty list means no filter: the webhook fires on every subscribed event.',
})
conditions!: WebhookFilterConditionDto[];
}
diff --git a/src/modules/webhook/filters/filter-validation.spec.ts b/src/modules/webhook/filters/filter-validation.spec.ts
index e7ddb09d1..0aa8b25e5 100644
--- a/src/modules/webhook/filters/filter-validation.spec.ts
+++ b/src/modules/webhook/filters/filter-validation.spec.ts
@@ -17,3 +17,11 @@ describe('collectFilterErrors (message-type enum)', () => {
expect(collectFilterErrors(typeCondition('banana'))).toEqual(['conditions[0].value "banana" is not a valid type']);
});
});
+
+describe('collectFilterErrors (empty conditions)', () => {
+ it('accepts an empty conditions list, which the published contract documents as "no filter"', () => {
+ // A client that cannot send `filters: null` (the Java SDK omits null fields) clears a filter
+ // with `{ conditions: [] }`, so this must stay valid.
+ expect(collectFilterErrors({ conditions: [] })).toEqual([]);
+ });
+});