Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
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.mdindex 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{