Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(webhook): document the bound on opt-in events
Yudhi Armyndharis501063ce9a78
diff --git a/.env.example b/.env.exampleindex f2c994861..8392755bd 100644--- a/.env.example+++ b/.env.example@@ -465,6 +465,11 @@ WEBHOOK_RETRY_DELAY=5000 # Base delay between retries in ms (doubles# plus this; more are shed to the outbox.# Deliveries to one session's failing receivers park at most# a quarter of it, so other sessions keep room to wait.+ # Opt-in events such as message.receipt are bounded per session+ # instead: a quarter of WEBHOOK_DISPATCH_CONCURRENCY run at+ # once and three quarters of this wait, and further ones are+ # dropped, not replayed, and counted in+ # openwa_webhook_delivery_failures_total.# Each inline delivery holds its event's inline media (up to# 4/3 x WEBHOOK_MEDIA_INLINE_MAX_BYTES as base64), up to about# 1.3 GiB per process at the defaults; QUEUE_ENABLED=true keepsdiff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex c1c9316ac..caa9ad444 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -4750,7 +4750,7 @@ Bare array of `WebhookDeliveryFailure` rows, ordered by `createdAt` descending.`replayable` is `true` when the row still holds the event data and can be replayed with [`POST /api/webhooks/delivery-failures/redrive`](#post-apiwebhooksdelivery-failuresredrive). The event data itself is never returned. Only terminal rows (`attempts` > 0) recorded while `WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS` > 0 keep it, and only until that window passes; with the default `0` every row reads `false`.-A delivery shed because the dispatch queue was full, or refused during shutdown, is recorded here with `attempts: 0` while its outbox row stays pending, so the outbox sweep replays it. With the queue disabled, a delivery that shutdown interrupts while it waits out a retry backoff is recorded the same way (`attempts: 0`, `lastError` `ConcurrencyLimiter closed`) if the backoff ends within `WEBHOOK_SHUTDOWN_DRAIN_MS`, although its earlier attempts were sent and their responses are not in the row; one still asleep when the drain ends is only logged (`webhook_delivery_abandoned_shutdown`). Either way its outbox row stays pending, and the replay on the next start replaces or clears the row. Any delivery the receiver accepts with a `2xx`, inline or from a queued job, removes the rows filed under its idempotency key, so a replay that succeeds leaves none. A replay that exhausts its retries files a row carrying the real error and attempt count and only then removes the `attempts: 0` row, so the event stays on record throughout, across a restart or a lost queue job too. A replay that fails before sending (a payload over the size cap after the `webhook:before` hooks, or one that cannot be serialized) gives the `attempts: 0` row that reason instead. A replay that keeps failing files no second row. `openwa_webhook_delivery_failures_total` counts the original shed, and counts once more if a replay also exhausts its retries.+A delivery shed because the dispatch queue was full, or refused during shutdown, is recorded here with `attempts: 0` while its outbox row stays pending, so the outbox sweep replays it. With the queue disabled, a delivery that shutdown interrupts while it waits out a retry backoff is recorded the same way (`attempts: 0`, `lastError` `ConcurrencyLimiter closed`) if the backoff ends within `WEBHOOK_SHUTDOWN_DRAIN_MS`, although its earlier attempts were sent and their responses are not in the row; one still asleep when the drain ends is only logged (`webhook_delivery_abandoned_shutdown`). Either way its outbox row stays pending, and the replay on the next start replaces or clears the row. Any delivery the receiver accepts with a `2xx`, inline or from a queued job, removes the rows filed under its idempotency key, so a replay that succeeds leaves none. A replay that exhausts its retries files a row carrying the real error and attempt count and only then removes the `attempts: 0` row, so the event stays on record throughout, across a restart or a lost queue job too. A replay that fails before sending (a payload over the size cap after the `webhook:before` hooks, or one that cannot be serialized) gives the `attempts: 0` row that reason instead. A replay that keeps failing files no second row. `openwa_webhook_delivery_failures_total` counts the original shed, and counts once more if a replay also exhausts its retries. It also counts each `message.receipt` dropped past the bound of its session (see Delivery semantics), which leaves no row here.**Errors:** `401` missing/invalid API key · `403` key role below ADMIN@@ -7229,7 +7229,7 @@ These are the events OpenWA actually emits. A webhook is registered with an `eve| `message.received` | An inbound message arrives | The full message object: `id`, `from`, `to`, `body`, `type`, `timestamp` (epoch **seconds**), `isGroup`, `kind` (user-facing chat discriminator of `chatId` — `individual\|group\|channel\|status\|broadcast\|unknown`), `fromMe`, `chatId`, `media{mimetype,filename?,data?,omitted?,sizeBytes?}` (media messages only), `contact{…}` (plus optional `senderPhone` for `@lid` senders, `order{orderId,token?}` / `product{productId,…}` on `order` / `product` messages, and `poll{name,options,allowMultipleAnswers}` on a poll creation message; on Baileys also `buttons:[{id,text}]` on a WhatsApp Business prompt that offers choices, and `button{id,text?}` when the sender tapped one) || `message.sent` | An outbound message is created/sent from this session | Same message object shape as `message.received` || `message.ack` | A delivery/read receipt updates an outbound message. On Baileys only 1:1 receipts advance it; opt-in `message.receipt` reports group and status receipts per participant and leaves the message at `sent`, see below | `{ id, messageId, status, ack, chatId? }` — `status` is the canonical state (`pending`/`sent`/`delivered`/`read`/`failed`); `ack` is the deprecated legacy integer derived from it; `chatId` is the conversation the acked message belongs to, present whenever the engine's update names the chat (both engines do on the live path) |-| `message.receipt` | One recipient receives, reads or plays a group or status message the account sent (**Baileys only**; not included in `*`) | `{ id, messageId, chatId, participant, status, timestamp }` ; one event per recipient and status; `status` is `delivered`/`read`/`played`, `timestamp` is epoch **seconds**. Receipts from the account's own linked devices are not reported. On Baileys 7.0.0-rc14 a played voice note reports `read`. Nothing is stored and `message.ack` is not advanced by it |+| `message.receipt` | One recipient receives, reads or plays a group or status message the account sent (**Baileys only**; not included in `*`) | `{ id, messageId, chatId, participant, status, timestamp }` ; one event per recipient and status; `status` is `delivered`/`read`/`played`, `timestamp` is epoch **seconds**. Receipts from the account's own linked devices are not reported. On Baileys 7.0.0-rc14 a played voice note reports `read`. Nothing is stored and `message.ack` is not advanced by it; per session a quarter of `WEBHOOK_DISPATCH_CONCURRENCY` run at once, three quarters of `WEBHOOK_DISPATCH_MAX_QUEUED` wait, and further ones are dropped, not replayed (see Delivery semantics) || `message.failed` | A receipt resolves to `failed` (dispatched in addition to `message.ack`) | `{ id, messageId, status: "failed", ack: -1, chatId? }`; `chatId` follows the same rules as `message.ack` || `message.revoked` | A message is deleted/recalled | `{ id, revokedId?, chatId, from, to, type: "revoked", body: "", timestamp }` — **reconcile on `revokedId`** (the original deleted message's id), falling back to `id`. On whatsapp-web.js `id` is the _revocation notification_ (a distinct message that won't match a stored id) and `revokedId` may be absent when the original isn't cached locally; on Baileys the two coincide || `message.reaction` | A reaction is added, changed, or removed | `{ messageId, chatId, reaction, senderId, reactions? }` — `reactions` is the post-apply `{ senderId: emoji }` snapshot, omitted when the gateway holds no stored copy of the message to compute it from (an ephemeral message, or one predating the session going live); treat it as unknown rather than empty and keep the map you already hold. `reaction` is empty when removed |@@ -7301,6 +7301,8 @@ Webhook delivery is **at-least-once**. A consumer can legitimately receive the sOutbox 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 for at most 10 s; direct sends, an operator redrive replay in flight, and an outbox replay in flight with its plugin hooks, get up to `WEBHOOK_SHUTDOWN_DRAIN_MS` (default 5s). That replay sends at most one more POST, bounded by `WEBHOOK_TIMEOUT`, and no further row is replayed; the next start replays what it left pending.+**Opt-in events are bounded, not replayed.** `message.receipt` fires once per recipient and status, so one flush of buffered receipts can be thousands of events in a tick. Each session passes a queue of its own before the shared dispatch pool: a quarter of `WEBHOOK_DISPATCH_CONCURRENCY` of its receipts run at once and up to three quarters of `WEBHOOK_DISPATCH_MAX_QUEUED` more wait their turn, which with the defaults delivers a flush of 500 in full and 754 of a flush of 2000. Any further receipt is dropped: it leaves no outbox or failure row and is not replayed, and it is counted in `openwa_webhook_delivery_failures_total` and logged once per burst (`webhook_opt_in_dropping` when the session starts dropping, then `webhook_opt_in_dropped` with the count). Because the queue is per session, one session's flood, or a receiver of its that never answers, does not shed or delay another session's events. Receipts still waiting at shutdown are dropped without being counted.+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/10-devops-infrastructure.md b/docs/10-devops-infrastructure.mdindex fd850c93d..396b4a243 100644--- a/docs/10-devops-infrastructure.md+++ b/docs/10-devops-infrastructure.md@@ -503,7 +503,10 @@ WEBHOOK_DISPATCH_MAX_QUEUED=1000# The failing state and the cap are held per process, not per cluster.# The first 2xx from the webhook lifts it. With the queue disabled, a session parks at most a# quarter of WEBHOOK_DISPATCH_MAX_QUEUED behind that limit and sheds the rest, so other sessions-# keep room. Each running, parked or backoff-waiting inline delivery holds its event's inline media+# keep room. Opt-in events such as message.receipt are bounded per session instead: a quarter of+# WEBHOOK_DISPATCH_CONCURRENCY run at once and three quarters of WEBHOOK_DISPATCH_MAX_QUEUED wait,+# and further ones are dropped, not replayed, and counted in openwa_webhook_delivery_failures_total.+# Each running, parked or backoff-waiting inline delivery holds its event's inline media# (up to 4/3 x WEBHOOK_MEDIA_INLINE_MAX_BYTES as base64), about 1.3 GiB per process at the defaults# when every slot is taken; lower these caps or enable the queue to reduce it.# WEBHOOK_DEGRADED_SESSION_CONCURRENCY=