Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(webhook): clarify replay and recovery behavior

Yudhi Armyndharisf5429cb0bc51
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index 2433d1a07..153e401b4 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -708,8 +708,8 @@ The data connection also owns:
- **`templates`** — reusable message templates (`src/modules/template/entities/template.entity.ts`), with a unique constraint on `(sessionId, name)` — one template name per session.
- **`status_updates`** — inbound status/story broadcasts with a 24-hour TTL (`src/modules/status-store/entities/status-update.entity.ts`); unique on `(sessionId, waStatusId)`. Attached media is stored via `StorageService`, not in the row.
-- **`webhook_delivery_failures`** — durable record of a webhook delivery that exhausted its retries, or was not sent (attempts 0) (`src/modules/webhook/entities/webhook-delivery-failure.entity.ts`), surfaced via the ADMIN `GET /webhooks/delivery-failures`. A shed or shutdown-refused delivery is replayed by the outbox until its replay budget runs out; an oversize payload or a preflight failure on first dispatch is not replayed. A later successful delivery removes the row. While `WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS` > 0 (default 0), a terminal row (attempts > 0) also keeps the pre-hook event data in `payload` (never selected by the listing, which reports `replayable` instead) so ADMIN `POST /webhooks/delivery-failures/redrive` can replay it with the stored idempotency key; the payload is cleared once that window passes and the row stays.
-- **`webhook_outbox_events`**: the outbound webhook delivery record (`src/modules/webhook/entities/webhook-outbox-event.entity.ts`): a row is written `pending` before the delivery attempt, so a delivery lost to a crash is replayed by the reconciler. It settles as `dispatched` once a durable owner (the BullMQ queue, or the inline POST in direct mode) holds it, or as `failed` when the replays run out or the reconciler finds the webhook removed, disabled or unsubscribed from the event (no failure row is written then). Settled rows drop their payload and are pruned on age (§5.7).
+- **`webhook_delivery_failures`**: durable record of a webhook delivery that exhausted its retries, or was not sent (attempts 0) (`src/modules/webhook/entities/webhook-delivery-failure.entity.ts`), surfaced via the ADMIN `GET /webhooks/delivery-failures`. A shed or shutdown-refused delivery is replayed by the outbox until its replay budget runs out; an oversize payload or a preflight failure on first dispatch is retired after its failure record is stored. A later successful delivery removes the row. While `WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS` > 0 (default 0), a terminal row (attempts > 0) also keeps the pre-hook event data in `payload` (never selected by the listing, which reports `replayable` instead) so ADMIN `POST /webhooks/delivery-failures/redrive` can replay it with the stored idempotency key; the payload is cleared once that window passes and the row stays.
+- **`webhook_outbox_events`**: the outbound delivery record (`src/modules/webhook/entities/webhook-outbox-event.entity.ts`). A successfully written `pending` row holds pre-hook event data before the attempt. Enqueue changes it to `queued` without dropping the payload. Delivery success, subscription invalidation or a successfully recorded terminal failure retires the copy; failed terminal recording leaves it available for reconciliation. The reconciler checks the stored job before replaying queued work and reuses its idempotency key. Settled rows drop their payload and are pruned on age (§5.7). Message persistence and outbox insertion remain separate transactions.
- **`send_idempotency_keys`**: one claimed `Idempotency-Key` per `(sessionId, idempotencyKey)` (unique) from the opt-in header on the message send routes (`src/modules/message/entities/send-idempotency-key.entity.ts`). The insert that wins the unique key runs the send; the row then holds `state` (`pending`, `completed` with the `responseBody` replayed to retries, or `failed` when the outcome is unknown), the `route` and a SHA-256 `requestHash` of route and body. Rows expire 24 hours after the claim (`expiresAt`) and are pruned hourly (§5.7). Not exported by `GET /infra/export-data`.
- **`plugin_instances`** — one configured instance of an adapter plugin, keyed `${pluginId}:${instanceId}` (`src/modules/integration/entities/plugin-instance.entity.ts`); holds the host-minted ingress HMAC secret, masked on API reads.
- **`ingress_events`** — persist-before-ack durable row and inbound dedup oracle, unique on `(pluginId, instanceId, providerDeliveryId)` (`src/modules/integration/entities/ingress-event.entity.ts`). The full payload is retired to `NULL` once dispatch is settled, leaving a slim dedup marker.
@@ -993,8 +993,8 @@ async cleanup(olderThanDays = 30): Promise<number> {
The other interval-based prunes are the same shape: one prune at startup, then a 24-hour `setInterval`, `unref`'d, never a `@Cron`:
-- **`webhook_delivery_failures`** — `WebhookService.onModuleInit()` (`src/modules/webhook/webhook.service.ts`), window `WEBHOOK_FAILURE_RETENTION_DAYS` (default 90; ≤ 0 disables the prune and logs that it is off). The replay `payload` has its own, shorter window: `WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS` (default 0, store none) clears expired payloads at startup and hourly; at 0 one startup pass clears any payload an earlier setting left.
-- **`webhook_outbox_events`**: `WebhookOutboxService.onModuleInit()` (`src/modules/webhook/webhook-outbox.service.ts`), window `WEBHOOK_OUTBOX_RETENTION_DAYS` (default 7). Only settled rows are deleted; a `pending` row is a delivery that can still be replayed and is never pruned on age. A non-positive value does **not** disable the prune: a settled row carries no payload, so the service warns and falls back to 7 days.
+- **`webhook_delivery_failures`**: `WebhookService.onModuleInit()` (`src/modules/webhook/webhook.service.ts`), window `WEBHOOK_FAILURE_RETENTION_DAYS` (default 90; ≤ 0 disables the prune and logs that it is off). The replay `payload` has its own, shorter window: `WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS` (default 0, store none) clears expired payloads at startup and hourly; at 0 one startup pass clears any payload an earlier setting left.
+- **`webhook_outbox_events`**: `WebhookOutboxService.onModuleInit()` (`src/modules/webhook/webhook-outbox.service.ts`), window `WEBHOOK_OUTBOX_RETENTION_DAYS` (default 7). Only settled rows are deleted; `pending` and `queued` rows can still be replayed and are never pruned on age. A non-positive value does **not** disable the prune: a settled row carries no payload, so the service warns and falls back to 7 days.
- **`ingress_events`** and **`integration_delivery_failures`** — `IntegrationRetentionService` (`src/modules/integration/integration-retention.service.ts`) prunes both in one timer on two independent windows. `INGRESS_DEDUP_RETENTION_DAYS` (default 7) bounds the dedup rows; a non-positive value does **not** disable it — an unpruned dedup table grows without bound for no functional gain, so the service warns and falls back to the 7-day default. `INGRESS_RETENTION_DAYS` (default 90) bounds the DLQ rows, where long retention can be a deliberate operator choice, so ≤ 0 disables that prune (and only that prune).
- **`messages`** and finished **`message_batches`**: `MessageRetentionService` (`src/modules/message/message-retention.service.ts`), window `MESSAGE_RETENTION_DAYS` (default 0, which keeps everything; boot rejects a value above 36500). Messages are deleted by `createdAt` in batches of 500 ids, at most 200 batches per run, so a run deletes at most 100,000 messages; a run that hits that limit logs a warning and is followed by another a minute later until the backlog is cleared. Pending and processing batches are never pruned. Once enabled, send pacing treats a contact silent for longer than the window as a new (cold) contact again, stats totals and search results shrink, archived media files are reclaimed by the chat-media orphan sweep, and a history sync does not write back messages older than the window. Search plugins get no `message:deleted` for pruned rows, so an external index keeps its copies.
- **`send_idempotency_keys`**: `SendIdempotencyService` (`src/modules/message/idempotency/send-idempotency.service.ts`) deletes rows past `expiresAt` (24 hours after the claim) on an hourly `setInterval`, with no startup run: a claim that collides with an expired row deletes it and claims the key itself, so a late prune never blocks a send.
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 2da23139c..307ae025f 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -7207,7 +7207,11 @@ Webhook delivery is **at-least-once**. A consumer can legitimately receive the s
- The underlying WhatsApp engine can re-fire an event for a single message.
- A failed delivery (non-2xx response, timeout, or network error) is retried.
-**Crash boundary.** Every delivery is recorded before it is attempted, and the record is retired once something durable owns it: the queue job in queued mode, the completed send in direct mode. A hard crash (SIGKILL, OOM) therefore leaves the record behind, and a bounded sweep (`WEBHOOK_RECONCILE_INTERVAL_MS`, default 60s) replays whatever is still stranded, reusing the stored `X-OpenWA-Idempotency-Key` so the retry stays deduplicable at your receiver. A delivery that keeps failing exhausts `WEBHOOK_RECONCILE_MAX_ATTEMPTS` and goes terminal rather than replaying forever. One window remains open: a crash between persisting the message and writing that record loses the delivery, because the two are not yet one transaction. The failure table records exhausted retries, plus over-budget, dispatch-capacity-exceeded, and shutdown-rejected deliveries with attempts 0. Read the last two as a report rather than a verdict: a delivery the dispatcher shed for capacity or refused during the drain was rejected before its POST, except a direct delivery the drain caught in a retry backoff, whose earlier attempts were sent, so it keeps its record until the same sweep replays it; a replay whose retries run out replaces that record with its own row, one that fails before sending gives it that reason, and one that delivers removes it. A node's sweep also leaves alone a delivery that the same node is still waiting to dispatch or retrying, however long that takes; with several nodes on one database, another node can still replay it, and the stored idempotency key keeps that duplicate deduplicable. Enabling the queue (`QUEUE_ENABLED=true`, needs Redis) makes the dispatch durable from the enqueue onward. In both modes, a graceful shutdown drains in-flight deliveries first: the queued path waits for each worker's current job, and the direct path waits up to `WEBHOOK_SHUTDOWN_DRAIN_MS` (default 5s; raise it to at least `WEBHOOK_TIMEOUT`, default 10s, if a slow receiver must finish).
+**Crash boundary.** A successfully written outbox record retains the pre-hook event data until delivery succeeds, the subscription becomes ineligible, or the terminal failure is stored. Queued records keep this copy even after enqueue; the worker retires it only after one of those outcomes. If failure recording fails, the copy remains eligible for recovery. The bounded sweep (`WEBHOOK_RECONCILE_INTERVAL_MS`, default 60s) checks the stored job before replaying, leaves active jobs alone, and reuses the stored `X-OpenWA-Idempotency-Key`. If Redis cannot confirm the job state, replay waits. A missing or failed job can be replayed within `WEBHOOK_RECONCILE_MAX_ATTEMPTS`; exhausting that budget retires the outbox only after terminal failure recording succeeds. Receiver deduplication remains necessary because a crash after receiver processing can cause another POST.
+
+Outbox creation is best effort, and message persistence and outbox insertion are separate transactions. A write failure or crash between them can still lose the webhook delivery. Failure records with zero attempts are excluded from operator redrive. Capacity and shutdown rejections can still be recovered from an unsettled outbox record; shutdown during retry backoff may follow earlier POSTs. The direct dispatcher leaves its local in-flight work alone during reconciliation. Graceful shutdown drains current queue jobs; direct sends wait up to `WEBHOOK_SHUTDOWN_DRAIN_MS` (default 5s).
+
+Before downgrading to a version that does not recognize the `queued` outbox state, drain or recover those records and take a backup. Its cleanup may otherwise treat an unsettled queued record as settled. Reverting the terminal-identity migration removes its index but does not restore historical duplicates.
**Design your handler to be idempotent**, keyed on the `X-OpenWA-Idempotency-Key` header (see below). As a server-side safety net, OpenWA de-duplicates inbound `message.received` before dispatch (a re-fired event for an already-persisted message is dropped), so one webhook normally sees each inbound message once — but this is best-effort defense-in-depth and does not remove the need for consumer-side idempotency.
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.md
index 9642bb2af..8c5c87dc7 100644
--- a/docs/18-sdk-design.md
+++ b/docs/18-sdk-design.md
@@ -243,17 +243,17 @@ Media bodies share the `SendMediaRequest` shape: `{ chatId, url? | base64?, mime
#### `webhooks`
-| Method | Signature | Description |
-| ------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `listAll` | `listAll(query?)` | List webhooks across EVERY session the key can see, not one session's. **OPERATOR** |
-| `deliveryFailures` | `deliveryFailures(query?)` | Deliveries that exhausted their retries (`attempts > 0`), or were shed, oversize, failed preflight or refused at shutdown, possibly between retries (`attempts: 0`); a later successful delivery removes the row — the diagnostic for a webhook that stopped arriving. A delivery a smart filter suppressed never reaches this log. **ADMIN** |
-| `redriveDeliveryFailures` | `redriveDeliveryFailures(body?)` | Replay the rows `deliveryFailures` marks `replayable` (kept while `WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS` > 0), oldest first, one bounded batch per call, reusing each stored idempotency key; returns the delivered/enqueued/failed/skipped/remaining counts. **ADMIN** |
-| `list` | `list(sessionId)` | List all webhooks for a session. **OPERATOR** |
-| `get` | `get(sessionId, id)` | Get a single webhook by id. **OPERATOR** |
-| `create` | `create(sessionId, body)` | Create a new webhook. **OPERATOR** |
-| `update` | `update(sessionId, id, body)` | Update a webhook. **OPERATOR** |
-| `delete` | `delete(sessionId, id)` | Delete a webhook. **OPERATOR** |
-| `test` | `test(sessionId, id)` | Trigger a test dispatch to the webhook URL and report the result. **OPERATOR** |
+| Method | Signature | Description |
+| ------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `listAll` | `listAll(query?)` | List webhooks across EVERY session the key can see, not one session's. **OPERATOR** |
+| `deliveryFailures` | `deliveryFailures(query?)` | Deliveries that exhausted their retries (`attempts > 0`), or were shed, oversize, failed preflight or refused at shutdown, possibly between retries (`attempts: 0`); a later successful delivery removes the row; the diagnostic for a webhook that stopped arriving. A delivery a smart filter suppressed never reaches this log. **ADMIN** |
+| `redriveDeliveryFailures` | `redriveDeliveryFailures(body?)` | Replay the rows `deliveryFailures` marks `replayable` (kept while `WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS` > 0), fewest attempts first, then oldest, one bounded batch per call, reusing each stored idempotency key; returns delivered/failed/skipped/remaining counts; `enqueued` is always 0. **ADMIN** |
+| `list` | `list(sessionId)` | List all webhooks for a session. **OPERATOR** |
+| `get` | `get(sessionId, id)` | Get a single webhook by id. **OPERATOR** |
+| `create` | `create(sessionId, body)` | Create a new webhook. **OPERATOR** |
+| `update` | `update(sessionId, id, body)` | Update a webhook. **OPERATOR** |
+| `delete` | `delete(sessionId, id)` | Delete a webhook. **OPERATOR** |
+| `test` | `test(sessionId, id)` | Trigger a test dispatch to the webhook URL and report the result. **OPERATOR** |
#### `labels` _(WhatsApp Business)_
@@ -621,17 +621,17 @@ Resources are accessed as properties on the client (e.g. `client.messages`). All
#### `client.webhooks`
-| Method | Signature | Description |
-| --------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `list_all` | `list_all(query=None) -> list[WebhookResponse]` | List webhooks across EVERY session the key can see, not one session's. **OPERATOR** |
-| `delivery_failures` | `delivery_failures(query=None) -> list[WebhookDeliveryFailure]` | Deliveries that exhausted their retries (`attempts > 0`), or were shed, oversize, failed preflight or refused at shutdown, possibly between retries (`attempts: 0`); a later successful delivery removes the row — the diagnostic for a webhook that stopped arriving. A delivery a smart filter suppressed never reaches this log. **ADMIN** |
-| `redrive_delivery_failures` | `redrive_delivery_failures(body=None) -> WebhookRedriveResult` | Replay the rows `delivery_failures` marks `replayable` (kept while `WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS` > 0), oldest first, one bounded batch per call, reusing each stored idempotency key; returns the delivered/enqueued/failed/skipped/remaining counts. **ADMIN** |
-| `list` | `list(session_id) -> list[WebhookResponse]` | List webhooks. **OPERATOR** |
-| `get` | `get(session_id, webhook_id) -> WebhookResponse` | Get one webhook. **OPERATOR** |
-| `create` | `create(session_id, body) -> WebhookResponse` | Create a webhook. **OPERATOR** |
-| `update` | `update(session_id, webhook_id, body) -> WebhookResponse` | Update a webhook. **OPERATOR** |
-| `delete` | `delete(session_id, webhook_id) -> None` | Delete a webhook. **OPERATOR** |
-| `test` | `test(session_id, webhook_id) -> WebhookTestResult` | Send a test delivery. **OPERATOR** |
+| Method | Signature | Description |
+| --------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_all` | `list_all(query=None) -> list[WebhookResponse]` | List webhooks across EVERY session the key can see, not one session's. **OPERATOR** |
+| `delivery_failures` | `delivery_failures(query=None) -> list[WebhookDeliveryFailure]` | Deliveries that exhausted their retries (`attempts > 0`), or were shed, oversize, failed preflight or refused at shutdown, possibly between retries (`attempts: 0`); a later successful delivery removes the row; the diagnostic for a webhook that stopped arriving. A delivery a smart filter suppressed never reaches this log. **ADMIN** |
+| `redrive_delivery_failures` | `redrive_delivery_failures(body=None) -> WebhookRedriveResult` | Replay the rows `delivery_failures` marks `replayable` (kept while `WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS` > 0), fewest attempts first, then oldest, one bounded batch per call, reusing each stored idempotency key; returns delivered/failed/skipped/remaining counts; `enqueued` is always 0. **ADMIN** |
+| `list` | `list(session_id) -> list[WebhookResponse]` | List webhooks. **OPERATOR** |
+| `get` | `get(session_id, webhook_id) -> WebhookResponse` | Get one webhook. **OPERATOR** |
+| `create` | `create(session_id, body) -> WebhookResponse` | Create a webhook. **OPERATOR** |
+| `update` | `update(session_id, webhook_id, body) -> WebhookResponse` | Update a webhook. **OPERATOR** |
+| `delete` | `delete(session_id, webhook_id) -> None` | Delete a webhook. **OPERATOR** |
+| `test` | `test(session_id, webhook_id) -> WebhookTestResult` | Send a test delivery. **OPERATOR** |
#### `client.labels` _(WhatsApp Business)_
@@ -974,17 +974,17 @@ All payloads are associative arrays; all listed methods are synchronous and retu
#### `webhooks`
-| Method | Signature | Description |
-| ------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `listAll` | `listAll(array $query = []): array` | List webhooks across EVERY session the key can see, not one session's. **OPERATOR** |
-| `deliveryFailures` | `deliveryFailures(array $query = [])` | Deliveries that exhausted their retries (`attempts > 0`), or were shed, oversize, failed preflight or refused at shutdown, possibly between retries (`attempts: 0`); a later successful delivery removes the row — the diagnostic for a webhook that stopped arriving. A delivery a smart filter suppressed never reaches this log. **ADMIN** |
-| `redriveDeliveryFailures` | `redriveDeliveryFailures(array $body = []): array` | Replay the rows `deliveryFailures` marks `replayable` (kept while `WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS` > 0), oldest first, one bounded batch per call, reusing each stored idempotency key; returns the delivered/enqueued/failed/skipped/remaining counts. **ADMIN** |
-| `list` | `list(string $sessionId): array` | List webhooks. **OPERATOR** |
-| `get` | `get(string $sessionId, string $id): array` | Get one webhook. **OPERATOR** |
-| `create` | `create(string $sessionId, array $body): array` | Create a webhook. **OPERATOR** |
-| `update` | `update(string $sessionId, string $id, array $body): array` | Update a webhook. **OPERATOR** |
-| `delete` | `delete(string $sessionId, string $id): void` | Delete a webhook. **OPERATOR** |
-| `test` | `test(string $sessionId, string $id): array` | Send a test event. **OPERATOR** |
+| Method | Signature | Description |
+| ------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `listAll` | `listAll(array $query = []): array` | List webhooks across EVERY session the key can see, not one session's. **OPERATOR** |
+| `deliveryFailures` | `deliveryFailures(array $query = [])` | Deliveries that exhausted their retries (`attempts > 0`), or were shed, oversize, failed preflight or refused at shutdown, possibly between retries (`attempts: 0`); a later successful delivery removes the row; the diagnostic for a webhook that stopped arriving. A delivery a smart filter suppressed never reaches this log. **ADMIN** |
+| `redriveDeliveryFailures` | `redriveDeliveryFailures(array $body = []): array` | Replay the rows `deliveryFailures` marks `replayable` (kept while `WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS` > 0), fewest attempts first, then oldest, one bounded batch per call, reusing each stored idempotency key; returns delivered/failed/skipped/remaining counts; `enqueued` is always 0. **ADMIN** |
+| `list` | `list(string $sessionId): array` | List webhooks. **OPERATOR** |
+| `get` | `get(string $sessionId, string $id): array` | Get one webhook. **OPERATOR** |
+| `create` | `create(string $sessionId, array $body): array` | Create a webhook. **OPERATOR** |
+| `update` | `update(string $sessionId, string $id, array $body): array` | Update a webhook. **OPERATOR** |
+| `delete` | `delete(string $sessionId, string $id): void` | Delete a webhook. **OPERATOR** |
+| `test` | `test(string $sessionId, string $id): array` | Send a test event. **OPERATOR** |
#### `labels` _(WhatsApp Business)_
diff --git a/sdk/go/webhooks.go b/sdk/go/webhooks.go
index 1123711ad..8b284f0b3 100644
--- a/sdk/go/webhooks.go
+++ b/sdk/go/webhooks.go
@@ -33,11 +33,11 @@ func (s *WebhooksService) DeliveryFailures(ctx context.Context, query *DeliveryF
}
// RedriveDeliveryFailures replays recorded deliveries that still hold their event data
-// (Replayable in DeliveryFailures), oldest first, one bounded batch per call. Each replay reuses the
-// stored idempotency key, so a receiver that already handled the event can dedup it. Only rows
+// (Replayable in DeliveryFailures), fewest attempts first, then oldest, one bounded batch per call.
+// Each replay reuses the stored idempotency key, so a receiver that already handled the event can dedup it. Only rows
// recorded while the gateway's WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS is above 0 are replayable.
// Requires an ADMIN-level key; rows outside the key's allowedSessions are never touched. A nil body
-// takes the oldest rows.
+// uses the default batch filter.
func (s *WebhooksService) RedriveDeliveryFailures(ctx context.Context, body *RedriveWebhookDeliveriesRequest) (*WebhookRedriveResult, error) {
if body == nil {
body = &RedriveWebhookDeliveriesRequest{}
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 ab5456fbf..2c048d7a3 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
@@ -47,12 +47,12 @@ public final class WebhooksResource {
/**
* Replay recorded deliveries that still hold their event data ({@code replayable} in {@link
- * #deliveryFailures}), oldest first, one bounded batch per call. Each replay reuses the stored
- * idempotency key, so a receiver that already handled the event can dedup it. Only rows recorded
+ * #deliveryFailures}), fewest attempts first, then oldest, one bounded batch per call.
+ * Each replay reuses the stored idempotency key, so a receiver that already handled the event can dedup it. Only rows recorded
* while the gateway's WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS is above 0 are replayable. Requires
* an ADMIN-level key; rows outside the key's allowedSessions are never touched.
*
- * @param body the batch filter; {@code null} takes the oldest rows
+ * @param body the batch filter; {@code null} uses the default batch filter
*/
public WebhookRedriveResult redriveDeliveryFailures(RedriveWebhookDeliveriesRequest body) {
return client.request(
diff --git a/sdk/javascript/src/resources/webhooks.ts b/sdk/javascript/src/resources/webhooks.ts
index df1d22920..0b47795c7 100644
--- a/sdk/javascript/src/resources/webhooks.ts
+++ b/sdk/javascript/src/resources/webhooks.ts
@@ -59,8 +59,8 @@ export class WebhooksResource {
/**
* Replay recorded deliveries that still hold their event data (`replayable: true` in
- * {@link deliveryFailures}), oldest first, one bounded batch per call. Each replay reuses the stored
- * idempotency key, so a receiver that already handled the event can dedup it. Only rows recorded
+ * {@link deliveryFailures}), fewest attempts first, then oldest, one bounded batch per call.
+ * Each replay reuses the stored idempotency key, so a receiver that already handled the event can dedup it. Only rows recorded
* while the gateway's `WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS` is above 0 are replayable. Requires
* an ADMIN-level key; rows outside the key's allowedSessions are never touched.
*/
diff --git a/sdk/php/src/Resources/WebhooksResource.php b/sdk/php/src/Resources/WebhooksResource.php
index 6c134843c..6ef81c3e0 100644
--- a/sdk/php/src/Resources/WebhooksResource.php
+++ b/sdk/php/src/Resources/WebhooksResource.php
@@ -57,13 +57,13 @@ class WebhooksResource
/**
* Replay recorded deliveries that still hold their event data (`replayable` in deliveryFailures),
- * oldest first, one bounded batch per call. Each replay reuses the stored idempotency key, so a
- * receiver that already handled the event can dedup it. Only rows recorded while the gateway's
+ * fewest attempts first, then oldest, one bounded batch per call. Each replay reuses the stored
+ * idempotency key, so a receiver that already handled the event can dedup it. Only rows recorded while the gateway's
* WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS is above 0 are replayable. Requires an ADMIN-level key;
* rows outside the key's allowedSessions are never touched.
*
* @param array<string,mixed> $body Optional filter: `sessionId`, `webhookId`, `ids` (at most 500),
- * `limit` (1-500, default 100). Empty takes the oldest rows.
+ * `limit` (1-500, default 100). Empty uses the default batch filter.
*
* @return array<string,mixed> `redriven`, `delivered`, `enqueued`, `failed`, `skipped`, `remaining`
*/
diff --git a/sdk/python/openwa/resources/webhooks.py b/sdk/python/openwa/resources/webhooks.py
index c195f2ef0..b1c382725 100644
--- a/sdk/python/openwa/resources/webhooks.py
+++ b/sdk/python/openwa/resources/webhooks.py
@@ -60,7 +60,7 @@ class WebhooksResource:
return self._http.request("GET", "/api/webhooks/delivery-failures", query=query)
def redrive_delivery_failures(self, body: RedriveWebhookDeliveriesRequest | None = None) -> WebhookRedriveResult:
- """Replay recorded deliveries that still hold their event data, oldest first, one bounded batch per call.
+ """Replay recorded deliveries in one bounded batch, fewest attempts first, then oldest.
Only rows with ``replayable: True`` in :meth:`delivery_failures` qualify: terminal rows recorded while
the gateway's ``WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS`` is above 0. Each replay reuses the stored