Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(api): update webhook url rules and the failure list scope

Yudhi Armyndhariscde2e3722786
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index c3b48fc29..661c455dc 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -4607,7 +4607,7 @@ Bare array, ordered by `createdAt` descending, bounded by `limit`/`offset`. If t
#### GET /api/webhooks/delivery-failures
-List webhook deliveries that exhausted every retry, most recent first. This is the dead-letter trail referenced by §6.6 — a receiver outage longer than the retry window, an over-budget payload, or a blocked (SSRF-guarded) URL lands here instead of vanishing.
+List webhook deliveries that exhausted their retries or were not sent (attempts 0, pending replay), most recent first. This is the dead-letter trail referenced by §6.6 — a receiver outage longer than the retry window, an over-budget payload, or a blocked (SSRF-guarded) URL lands here instead of vanishing.
**Auth:** API key (ADMIN) · **Scope:** results are confined to the calling key's `allowedSessions`, so a session-restricted ADMIN key cannot read another session's rows via `sessionId`
@@ -4661,7 +4661,7 @@ Create a webhook for the session.
| 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. |
+| url | string | yes | `@IsUrl({ require_tld: false, require_protocol: true, protocols: ['http', 'https'] })` (allows hostnames without a dot, e.g. `http://localhost:3000`), `@MaxLength(2048)`; also run through the SSRF guard, which can reject with `400`. | 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-]+$/` and are unique ignoring case, 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`, `user-agent` 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 `{}`. |
@@ -4725,15 +4725,15 @@ Update a webhook. Partial — only fields present in the body are changed.
**Request body** — `UpdateWebhookDto` (all fields optional; only fields where the value is not `undefined` are applied)
-| Field | Type | Required | Constraints | Description |
-| ---------- | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| url | string | no | omit to skip (explicit `null` → `400`), `@IsUrl({ require_tld: false })`; re-runs the SSRF guard when provided → `400` if blocked. | New URL. |
-| events | string[] | no | omit to skip (explicit `null` → `400`), `@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 | omit to skip (explicit `null` → `400`), `@IsHeaderMap()` (same constraints as create) | **Write-only.** Replaces existing headers wholesale when provided. |
-| filters | WebhookFilters \| null | no | `@IsOptional`, `@IsValidWebhookFilters()` | Set to `null` or `{ conditions: [] }` to clear filters. |
-| active | boolean | no | omit to skip (explicit `null` → `400`), `@IsBoolean` | Enable/disable the webhook. (Present only on update, not create.) |
-| retryCount | number (int) | no | omit to skip (explicit `null` → `400`), `@IsInt`, `@Min(0)`, `@Max(5)` | Total delivery attempts per event, including the first. |
+| Field | Type | Required | Constraints | Description |
+| ---------- | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| url | string | no | omit to skip (explicit `null` → `400`), `@IsUrl({ require_tld: false, require_protocol: true, protocols: ['http', 'https'] })`, `@MaxLength(2048)`; re-runs the SSRF guard when provided → `400` if blocked. | New URL. |
+| events | string[] | no | omit to skip (explicit `null` → `400`), `@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 | omit to skip (explicit `null` → `400`), `@IsHeaderMap()` (same constraints as create) | **Write-only.** Replaces existing headers wholesale when provided. |
+| filters | WebhookFilters \| null | no | `@IsOptional`, `@IsValidWebhookFilters()` | Set to `null` or `{ conditions: [] }` to clear filters. |
+| active | boolean | no | omit to skip (explicit `null` → `400`), `@IsBoolean` | Enable/disable the webhook. (Present only on update, not create.) |
+| retryCount | number (int) | no | omit to skip (explicit `null` → `400`), `@IsInt`, `@Min(0)`, `@Max(5)` | Total delivery attempts per event, including the first. |
```json
{