Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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` ma
plugin 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 its
declarative `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 delay
diff --git a/openapi.json b/openapi.json
index 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.ts
index 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.ts
index 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);