Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
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.mdindex 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 most5 s per event. The same fail-open value drains in-flight hooks if the worker crashes. The timeout islogged 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 eventloop is blocked (a synchronous loop) cannot answer within 5 s, so it is terminated and the plugin isset 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.mdindex 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 callsconnects. Providers already deliver over unordered, at-least-once HTTP, so plugin handlers must beidempotent 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 (default10). A burst on one lane larger than that fills every slot with same-lane waiters, and events for otherconversations and instances queue behind the burst until it drains. Size `INGRESS_WORKER_CONCURRENCY`