Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(ingress): state what a re-delivery is actually answered with
Yudhi Armyndharis68351b20eb3c
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex bb788ddce..6861386c8 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -6757,7 +6757,10 @@ the provider's verification handshake and answers only when its `verifyToken` maplugin processing. `200` means the `GET` verification-challenge echo, or a route whose declared`ack` sets it. A route may shape the synchronous status/body/headers the provider sees via itsdeclarative `ack` config (doc 25); the plugin itself always runs async. A re-delivery of an-already-persisted event is answered with that same ack, byte for byte, and is not enqueued again.+already-persisted event is answered with the route's ack, with the same status and headers as the+first delivery, and is not enqueued again. The ack is rendered from the retry, so `{timestamp}` in+an ack body is the retry's time and `{rawBody}` is the retry's body. A retry still passes the checks+that run before dedup: while a `session-alive` route's bound session is down it gets the `503`.**Errors:** `401` signature verification failed (missing, stale, or wrong secret) · `403` `GET` verification challenge failed (`verifyToken` mismatch) · `404` unknown pluginId/instanceId, or no such claimed route · `413` body over the route's `maxBodyBytes` · `429` rate limit: the per-instance bucket (`INGRESS_INSTANCE_LIMIT`) or the per-client-IP bucket (`INGRESS_IP_LIMIT`), both per `INGRESS_INSTANCE_TTL`; the global per-IP tiers skip this route, so these two are its bounds, and `Retry-After-instance` / `Retry-After-ingress-ip` names the one that shed the request, alongside a plain `Retry-After` carrying the same delay · `503` a route declaring a `session-alive` preflight whose bound session is not connected: the delivery is not persisted, so the provider's retry is treated as a new delivery, and `Retry-After` carries the delaydiff --git a/openapi.json b/openapi.jsonindex 9e3b229b3..2438f824c 100644--- a/openapi.json+++ b/openapi.json@@ -8914,7 +8914,7 @@],"responses": {"200": {- "description": "GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery is answered with the same ack as the first delivery, so it is not distinguishable by status."+ "description": "GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery that reaches the dedup check is answered with the route's ack (same status and headers as the first delivery), so it is not distinguishable by status."},"202": {"description": "Webhook accepted and queued for async plugin processing (the primary success path)."@@ -8975,7 +8975,7 @@],"responses": {"200": {- "description": "GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery is answered with the same ack as the first delivery, so it is not distinguishable by status."+ "description": "GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery that reaches the dedup check is answered with the route's ack (same status and headers as the first delivery), so it is not distinguishable by status."},"202": {"description": "Webhook accepted and queued for async plugin processing (the primary success path)."@@ -9036,7 +9036,7 @@],"responses": {"200": {- "description": "GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery is answered with the same ack as the first delivery, so it is not distinguishable by status."+ "description": "GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery that reaches the dedup check is answered with the route's ack (same status and headers as the first delivery), so it is not distinguishable by status."},"202": {"description": "Webhook accepted and queued for async plugin processing (the primary success path)."@@ -9097,7 +9097,7 @@],"responses": {"200": {- "description": "GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery is answered with the same ack as the first delivery, so it is not distinguishable by status."+ "description": "GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery that reaches the dedup check is answered with the route's ack (same status and headers as the first delivery), so it is not distinguishable by status."},"202": {"description": "Webhook accepted and queued for async plugin processing (the primary success path)."@@ -9158,7 +9158,7 @@],"responses": {"200": {- "description": "GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery is answered with the same ack as the first delivery, so it is not distinguishable by status."+ "description": "GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery that reaches the dedup check is answered with the route's ack (same status and headers as the first delivery), so it is not distinguishable by status."},"202": {"description": "Webhook accepted and queued for async plugin processing (the primary success path)."@@ -9219,7 +9219,7 @@],"responses": {"200": {- "description": "GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery is answered with the same ack as the first delivery, so it is not distinguishable by status."+ "description": "GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery that reaches the dedup check is answered with the route's ack (same status and headers as the first delivery), so it is not distinguishable by status."},"202": {"description": "Webhook accepted and queued for async plugin processing (the primary success path)."@@ -9280,7 +9280,7 @@],"responses": {"200": {- "description": "GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery is answered with the same ack as the first delivery, so it is not distinguishable by status."+ "description": "GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery that reaches the dedup check is answered with the route's ack (same status and headers as the first delivery), so it is not distinguishable by status."},"202": {"description": "Webhook accepted and queued for async plugin processing (the primary success path)."diff --git a/src/modules/integration/ingress.controller.ts b/src/modules/integration/ingress.controller.tsindex d49a92a7b..43368eaa2 100644--- a/src/modules/integration/ingress.controller.ts+++ b/src/modules/integration/ingress.controller.ts@@ -46,12 +46,16 @@ export class IngressController {name: 'path',type: String,description:- 'The plugin-declared route: a single path segment. Only the first segment selects the route; any further segments are ignored.',+ 'The plugin-declared route: a single path segment. ' ++ 'Only the first segment selects the route; any further segments are ignored.',example: 'chatwoot',})@ApiOkResponse({description:- 'GET verification challenge echo, or a route whose declared ack sets 200. Not the primary success path; see 202. A re-delivery is answered with the same ack as the first delivery, so it is not distinguishable by status.',+ 'GET verification challenge echo, or a route whose declared ack sets 200. ' ++ 'Not the primary success path; see 202. ' ++ "A re-delivery that reaches the dedup check is answered with the route's ack " ++ '(same status and headers as the first delivery), so it is not distinguishable by status.',})@ApiResponse({status: 202,diff --git a/src/modules/integration/ingress.service.ts b/src/modules/integration/ingress.service.tsindex 02555aa95..a486c5433 100644--- a/src/modules/integration/ingress.service.ts+++ b/src/modules/integration/ingress.service.ts@@ -186,9 +186,10 @@ export class IngressService {body: req.rawBody,rawBody: req.rawBody,};- // Rendered BEFORE the dedup check so a provider retry gets the byte-identical ack rather than a- // second contract on the same route. The ctx is the request in hand (rawBody, deliveryId, now),- // never stored state, which is what makes rendering it on a dedup hit sound: an ack field that had+ // Rendered BEFORE the dedup check so a provider retry gets the route's ack (same status and headers)+ // rather than a second contract on the same route. A body template renders from the retry, not the+ // first delivery, and a retry still passes the preflight above first. The ctx is the request in+ // hand (rawBody, deliveryId, now), never stored state, which is what makes rendering it on a dedup hit sound: an ack field that had// to reflect the PERSISTED row would echo the retry's values as the original's. Keep it that way.const ack = renderAck(route.response?.ack, {rawBody: req.rawBody,@@ -206,7 +207,7 @@ export class IngressService {payloadHash: createHash('sha256').update(req.rawBody).digest('hex'),sessionId: instance.sessionScope,});- if (!isNew) return ack; // already persisted/acked; a retry gets the first delivery's ack+ if (!isNew) return ack; // already persisted/acked; a retry gets the route's ack, not enqueued again// Best-effort conversation id for P1 ordering. Never throws — a malformed body just yields undefined.const providerConversationId = extractConversationId(route.conversationId, req.headers, req.rawBody);