Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(plugins): state the webhook handler budget and what an overrun does

Yudhi Armyndharis91a5eecd5f6b
diff --git a/docs/19-plugin-architecture.md b/docs/19-plugin-architecture.md
index 07a65364d..04470d69b 100644
--- a/docs/19-plugin-architecture.md
+++ b/docs/19-plugin-architecture.md
@@ -798,6 +798,9 @@ tier automatically. Key properties:
resolves `{ continue: true }` (fail-open), so each sandboxed subscriber delays the hook chain by at most
5 s per event. The same fail-open value drains in-flight hooks if the worker crashes. The timeout is
logged at most once per event per minute and shows as the last hook error in plugin health.
+- A sandboxed **webhook** handler (`ctx.registerWebhook`) has the same **5 s** budget (`INGRESS_DISPATCH_TIMEOUT_MS`), and the host
+ cannot cancel a handler that overruns it: the delivery is retried while the first run still lands, so a handler must key
+ its side effects on `req.deliveryId` and hand slow work to a background task (docs/25, section 25.7).
- After a hook, webhook or search dispatch times out, the host pings the worker. A worker whose event
loop is blocked (a synchronous loop) cannot answer within 5 s, so it is terminated and the plugin is
set to `ERROR`, as on a crash; a slow async handler answers and is left running.
diff --git a/docs/25-integration-fabric.md b/docs/25-integration-fabric.md
index 2aac572f2..e5f113288 100644
--- a/docs/25-integration-fabric.md
+++ b/docs/25-integration-fabric.md
@@ -241,6 +241,15 @@ dispatch when Redis is unreachable. Before Redis has ever connected, queue calls
connects. Providers already deliver over unordered, at-least-once HTTP, so plugin handlers must be
idempotent and treat ingress as a reconciliation trigger.
+A plugin's webhook handler has **5 s** (`INGRESS_DISPATCH_TIMEOUT_MS`) to finish. The host cannot cancel a
+handler that overruns it: the attempt is recorded as failed, the conversation lock is released and the
+delivery is retried (queued) or dead-lettered (inline), while the first run goes on and its work still
+lands. A handler that calls a slow upstream, or sends media, can therefore run twice for one delivery.
+Key every side effect on the delivery id (`req.deliveryId`) and hand work that can outlast the budget to
+a background task instead of awaiting it in the handler. The budget is short because a queue-disabled
+deployment answers the provider only after the inline dispatch, and providers abandon a request within a
+few seconds.
+
A job waiting on that lock still holds one of the `INGRESS_WORKER_CONCURRENCY` worker slots (default
10). A burst on one lane larger than that fills every slot with same-lane waiters, and events for other
conversations and instances queue behind the burst until it drains. Size `INGRESS_WORKER_CONCURRENCY`