Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(webhooks): describe retryCount as total delivery attempts

Yudhi Armyndharisc4140109e6a6
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 0e8b03c6c..d0345999a 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -4593,7 +4593,7 @@ Create a webhook for the session.
| 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)` | Delivery retry attempts on failure. Defaults to `3`. |
+| 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
{
@@ -4660,7 +4660,7 @@ Update a webhook. Partial — only fields present in the body are changed.
| 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. |
| 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)` | Retry attempts. |
+| retryCount | number (int) | no | `@IsOptional`, `@IsInt`, `@Min(0)`, `@Max(5)` | Total delivery attempts per event, including the first. |
```json
{
diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.md
index 97bfaf166..6fb2c8655 100644
--- a/docs/10-devops-infrastructure.md
+++ b/docs/10-devops-infrastructure.md
@@ -487,7 +487,7 @@ WEBHOOK_TIMEOUT=10000
WEBHOOK_RETRY_DELAY=5000
WEBHOOK_DISPATCH_CONCURRENCY=16
WEBHOOK_DISPATCH_MAX_QUEUED=1000
-# Retry attempts are configured per webhook with the retryCount API field (default 3, range 0-5).
+# Delivery attempts (total, including the first) are set per webhook with the retryCount API field (default 3, range 0-5).
# ===========================================
# RATE LIMITING
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 9c34ebeaf..6d1e67fc1 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -901,8 +901,8 @@ curl -X POST http://localhost:2785/api/sessions/{sessionId}/webhooks \
}'
```
-`retryCount` (0–5, default 3) is per webhook. The delivery timings are process-wide environment
-variables:
+`retryCount` (0–5, default 3) is per webhook and counts total delivery attempts, including the first, so `1`
+retries nothing. The delivery timings are process-wide environment variables:
```bash
WEBHOOK_TIMEOUT=10000 # per-attempt HTTP timeout in ms (default 10000)
diff --git a/openapi.json b/openapi.json
index eb64ae196..82b67d8c9 100644
--- a/openapi.json
+++ b/openapi.json
@@ -11123,7 +11123,7 @@
},
"retryCount": {
"type": "number",
- "description": "Number of retry attempts on failure",
+ "description": "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.",
"example": 3,
"minimum": 0,
"maximum": 5
@@ -11319,7 +11319,7 @@
},
"retryCount": {
"type": "number",
- "description": "Delivery attempts before the webhook is parked. Same range the create route enforces.",
+ "description": "Total delivery attempts per event, including the first (0 and 1 both mean a single attempt). Same range the create route enforces.",
"example": 3,
"minimum": 0,
"maximum": 5
diff --git a/src/modules/webhook/dto/webhook.dto.ts b/src/modules/webhook/dto/webhook.dto.ts
index 651bcdeb1..d7af02fbd 100644
--- a/src/modules/webhook/dto/webhook.dto.ts
+++ b/src/modules/webhook/dto/webhook.dto.ts
@@ -168,7 +168,10 @@ export class CreateWebhookDto {
filters?: WebhookFilters | null;
@ApiPropertyOptional({
- description: 'Number of retry attempts on failure',
+ description:
+ '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.',
example: 3,
minimum: 0,
maximum: 5,
@@ -253,7 +256,9 @@ export class UpdateWebhookDto {
active?: boolean;
@ApiPropertyOptional({
- description: 'Delivery attempts before the webhook is parked. Same range the create route enforces.',
+ description:
+ 'Total delivery attempts per event, including the first (0 and 1 both mean a single attempt). Same ' +
+ 'range the create route enforces.',
example: 3,
minimum: 0,
maximum: 5,