Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(webhook): note when a webhook's opt-in share is fixed
Yudhi Armyndharis891e4f4de43f
diff --git a/.env.example b/.env.exampleindex 084b8e3a4..4d71b57b9 100644--- a/.env.example+++ b/.env.example@@ -476,7 +476,10 @@ WEBHOOK_RETRY_DELAY=5000 # Base delay between retries in ms (doubles# is shared: a session holds up to four at once (one per webhook# past four), and another session's events wait for a slot once# such sessions together hold all of them, four sessions at the- # defaults. The events waiting are not capped process-wide.+ # defaults. A webhook's share is fixed when its queue is created+ # and kept while it has events, so receipt webhooks added+ # meanwhile can briefly raise a session above four. The events+ # waiting are not capped process-wide.# 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 1fe4aef9d..45e7f26db 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -7301,7 +7301,7 @@ 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 webhook that names it has a queue of its own before the shared dispatch pool: a quarter of `WEBHOOK_DISPATCH_CONCURRENCY` deliveries run at once, divided among the session's webhooks that name `message.receipt` and never fewer than one running delivery per webhook, and up to three quarters of `WEBHOOK_DISPATCH_MAX_QUEUED` more receipts wait their turn. With the defaults a flush of 500 is delivered in full and at least 750 of a flush of 2000 (754 with one webhook, 751 with four). A flush drains at that quarter of the pool: 750 receipts to a receiver that takes 30 ms each take about 6 s, or about 24 s when four webhooks share the quarter. Any further receipt is dropped for that webhook: it leaves no outbox or failure row, is not replayed, and is counted in `openwa_webhook_delivery_failures_total` once for each webhook it is dropped for. It is logged once per burst and webhook (`webhook_opt_in_dropping` when the webhook starts dropping, then `webhook_opt_in_dropped` with the count). A webhook's queue is its own, so a receiver of it that never answers holds only that webhook's places: the session's other webhooks and its other events are not slowed. Between sessions the isolation has a limit, because the dispatch pool is shared. A receiver that never answers holds its places for a `WEBHOOK_TIMEOUT`; a session holds up to four at once, or one per webhook when it has more than four. An event of another session waits for a slot once such sessions together hold all `WEBHOOK_DISPATCH_CONCURRENCY` of them, which at the defaults is four sessions: it then waits one `WEBHOOK_TIMEOUT` with four or five, two with eight. The receipts waiting in all queues together are not capped. Receipts still waiting at shutdown are dropped without being counted.+**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 webhook that names it has a queue of its own before the shared dispatch pool: a quarter of `WEBHOOK_DISPATCH_CONCURRENCY` deliveries run at once, divided among the session's webhooks that name `message.receipt` and never fewer than one running delivery per webhook, and up to three quarters of `WEBHOOK_DISPATCH_MAX_QUEUED` more receipts wait their turn. With the defaults a flush of 500 is delivered in full and at least 750 of a flush of 2000 (754 with one webhook, 751 with four). A flush drains at that quarter of the pool: 750 receipts to a receiver that takes 30 ms each take about 6 s, or about 24 s when four webhooks share the quarter. Any further receipt is dropped for that webhook: it leaves no outbox or failure row, is not replayed, and is counted in `openwa_webhook_delivery_failures_total` once for each webhook it is dropped for. It is logged once per burst and webhook (`webhook_opt_in_dropping` when the webhook starts dropping, then `webhook_opt_in_dropped` with the count). A webhook's queue is its own, so a receiver of it that never answers holds only that webhook's places: the session's other webhooks and its other events are not slowed. Between sessions the isolation has a limit, because the dispatch pool is shared. A receiver that never answers holds its places for a `WEBHOOK_TIMEOUT`; a session holds up to four at once, or one per webhook when it has more than four. That share is fixed when a webhook's queue is created and kept while the queue has events, so a session that adds receipt webhooks while a queue is busy can briefly hold more places than this. An event of another session waits for a slot once such sessions together hold all `WEBHOOK_DISPATCH_CONCURRENCY` of them, which at the defaults is four sessions: it then waits one `WEBHOOK_TIMEOUT` with four or five, two with eight. The receipts waiting in all queues together are not capped. 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.diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.mdindex f36c6705a..6df25b93e 100644--- a/docs/10-devops-infrastructure.md+++ b/docs/10-devops-infrastructure.md@@ -510,7 +510,9 @@ WEBHOOK_DISPATCH_MAX_QUEUED=1000# openwa_webhook_delivery_failures_total. A webhook whose receiver never answers holds only its own# places, but the pool is shared: a session holds up to four at once (one per webhook past four), and# another session's events wait for a slot once such sessions together hold all of them, which-# is four sessions at the defaults. There is no process-wide cap on the events waiting.+# is four sessions at the defaults. A webhook's share is fixed when its queue is created and kept while+# it has events, so receipt webhooks added meanwhile can briefly raise a session above four. There is+# no process-wide cap on the events waiting.# 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.