Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(ingress): let a route key retries on the body when the provider rotates its delivery id

Yudhi Armyndharis441040cee0d7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4be42a7ee..ed9aeb2d7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
+- An ingress route can declare `dedupOn: "body"` to key provider retries on the raw body instead of the delivery-id header. A provider that mints a fresh delivery id on every retry attempt, as supabase/auth does inside its hook retry loop, was never deduplicated when an ack was lost, so the contact received the message twice; routes that do not declare it keep the header ([#1641](https://github.com/rmyndharis/OpenWA/issues/1641)).
- Baileys sessions record a message the account sent from its phone while the gateway was down, and dispatch `message.sent` for it, as they already did for one sent while the gateway was online. The offline replay carried the same `append` tag as the library's echo of an API send, which the upsert handler dropped wholesale; it now skips only the ids this session sent itself, and the phone's reactions, edits and revokes from that window are replayed the same way ([#1667](https://github.com/rmyndharis/OpenWA/issues/1667)).
- Baileys sessions no longer drop the inbound messages WhatsApp queued while they were down. The offline replay is tagged `append`, which the upsert handler treated as history and skipped for anything older than the reconnect, so every message sent during an outage was never stored and never dispatched ([#1660](https://github.com/rmyndharis/OpenWA/issues/1660)). Thanks @fransarni for the report.
- A whatsapp-web.js session that comes up without its page-side call hook says so in the log instead of silently never reporting an incoming call. The hook is installed last in the same page evaluate as the message listeners, so the session stays healthy for messages either way ([#1655](https://github.com/rmyndharis/OpenWA/issues/1655)).
diff --git a/docs/25-integration-fabric.md b/docs/25-integration-fabric.md
index c1f0b69b7..3e1acedc2 100644
--- a/docs/25-integration-fabric.md
+++ b/docs/25-integration-fabric.md
@@ -166,7 +166,11 @@ Four tables live on the data connection, each created by a hand-authored dual-di
`(pluginId, instanceId, providerDeliveryId)` deduplication plus a queue job id keyed on the delivery id
provides best-effort de-duplication when the provider supplies a stable delivery id. Standard Webhooks defaults
to its signed `webhook-id`; other handlers must remain idempotent because arbitrary provider headers
- are not authenticated by every scheme. Freshness is enforced whenever a route declares
+ are not authenticated by every scheme. A route whose provider mints a fresh delivery id on every retry
+ attempt can declare `dedupOn: "body"` to key retries on the raw body instead: byte-identical bodies
+ then collapse within `INGRESS_DEDUP_RETENTION_DAYS`, the persisted delivery id and the `{id}` ack
+ token become that content hash, and a provider whose retries legitimately differ in the signed body
+ should keep the default, since `body` would dedup nothing for it. Freshness is enforced whenever a route declares
`signature.timestampHeader`: the declared `toleranceSec` wins, and otherwise the host default
(`INGRESS_TIMESTAMP_TOLERANCE_SEC`, default 300) applies — a declared timestamp is never accepted
without a freshness check. Freshness alone is not replay protection, though: an **unsigned**
diff --git a/src/core/plugins/plugin-manifest-ingress.spec.ts b/src/core/plugins/plugin-manifest-ingress.spec.ts
index 73b81c8fd..fd41f547e 100644
--- a/src/core/plugins/plugin-manifest-ingress.spec.ts
+++ b/src/core/plugins/plugin-manifest-ingress.spec.ts
@@ -72,6 +72,18 @@ describe('validateIngressManifest', () => {
expect(() => validateIngressManifest(m as never)).toThrow(/toleranceSec/);
});
+ it('rejects a dedupOn value other than header or body', () => {
+ const m = baseManifest();
+ (m.ingress[0] as { dedupOn?: string }).dedupOn = 'bdy';
+ expect(() => validateIngressManifest(m as never)).toThrow(/dedupOn/);
+ });
+
+ it('accepts dedupOn: body', () => {
+ const m = baseManifest();
+ (m.ingress[0] as { dedupOn?: string }).dedupOn = 'body';
+ expect(() => validateIngressManifest(m as never)).not.toThrow();
+ });
+
it('rejects a duplicate route within one manifest', () => {
const m = baseManifest();
m.ingress.push({ ...m.ingress[0] });
diff --git a/src/core/plugins/plugin.interfaces.ts b/src/core/plugins/plugin.interfaces.ts
index 09e477f1a..676f795c4 100644
--- a/src/core/plugins/plugin.interfaces.ts
+++ b/src/core/plugins/plugin.interfaces.ts
@@ -268,6 +268,16 @@ export interface PluginIngressRoute {
// ordering key (P1). Absent => the P1 lock falls back to per-instance serialization. The host never
// needs to understand the provider's schema beyond this one pointer.
conversationId?: { header?: string; jsonPointer?: string };
+ /**
+ * What identifies a retry of the same delivery. `header` (the default) trusts the dedup header
+ * whenever the provider sends one and falls back to a hash of the raw body only when it is
+ * absent. `body` keys every delivery on that hash regardless of the header, for a provider that
+ * mints a fresh delivery id on each retry attempt, so its retries would otherwise never dedup.
+ * Byte-identical bodies collapse within `INGRESS_DEDUP_RETENTION_DAYS`; a provider whose retries
+ * legitimately differ in the body (a fresh timestamp or nonce inside the signed payload) keeps
+ * the default, since `body` would then dedup nothing.
+ */
+ dedupOn?: 'header' | 'body';
/** Optional synchronous-response contract (host-side preflight + ack). Additive; absent = today's
* default 202 fast-ack, byte-identical. Validated by validateIngressManifest. */
response?: IngressResponseContract;
@@ -348,6 +358,11 @@ export function validateIngressManifest(manifest: PluginManifest, allowUnsignedI
`Plugin ${manifest.id}: route '${r.route}' toleranceSec must be > 0 (a replay guard would be a no-op)`,
);
}
+ if (r.dedupOn !== undefined && r.dedupOn !== 'header' && r.dedupOn !== 'body') {
+ throw new Error(
+ `Plugin ${manifest.id}: route '${r.route}' dedupOn must be 'header' or 'body' (got '${String(r.dedupOn)}')`,
+ );
+ }
if (r.response) {
const ackStatus = r.response.ack?.status;
if (ackStatus !== undefined && (!Number.isInteger(ackStatus) || ackStatus < 100 || ackStatus > 599)) {
diff --git a/src/modules/integration/ingress.service.spec.ts b/src/modules/integration/ingress.service.spec.ts
index 0328439fd..fec11df96 100644
--- a/src/modules/integration/ingress.service.spec.ts
+++ b/src/modules/integration/ingress.service.spec.ts
@@ -495,6 +495,53 @@ describe('IngressService.handle', () => {
});
});
+describe('dedupOn: body (a provider that rotates its delivery id on retry)', () => {
+ // supabase/auth mints a fresh webhook-id for every attempt inside its own retry loop, so a lost
+ // ack means the same signed body arrives under a new id and is treated as a new delivery: the
+ // contact receives a second OTP. A route can declare that the body, not the header, is the
+ // retry key; the header keeps deciding for every route that does not.
+ // The request fixture above is scoped to the service describe, so this block carries its own.
+ const req = {
+ pluginId: 'chatwoot',
+ instanceId: 'acct1',
+ route: 'chatwoot',
+ method: 'POST',
+ headers: { 'x-delivery': 'd1' },
+ query: {},
+ rawBody: '{}',
+ };
+ const bodyKeyedRoute = () => ({
+ route: 'send-sms',
+ mode: 'async',
+ verify: 'core',
+ maxBodyBytes: 1024,
+ // scheme none, as the fixture above: this block is about the retry key, not the signature.
+ signature: { scheme: 'none' },
+ dedupHeader: 'webhook-id',
+ dedupOn: 'body',
+ });
+
+ it('keys the delivery on the body even when the dedup header is present', async () => {
+ const first = deps({ manifestRoute: jest.fn().mockReturnValue(bodyKeyedRoute()) });
+ await new IngressService(first).handle({ ...req, headers: { 'webhook-id': 'attempt-1' } });
+ const firstId = (first.enqueue.mock.calls[0] as [unknown, string])[1];
+
+ const retry = deps({ manifestRoute: jest.fn().mockReturnValue(bodyKeyedRoute()) });
+ await new IngressService(retry).handle({ ...req, headers: { 'webhook-id': 'attempt-2' } });
+ expect((retry.enqueue.mock.calls[0] as [unknown, string])[1]).toBe(firstId);
+
+ const other = deps({ manifestRoute: jest.fn().mockReturnValue(bodyKeyedRoute()) });
+ await new IngressService(other).handle({ ...req, headers: { 'webhook-id': 'attempt-3' }, rawBody: '{"a":1}' });
+ expect((other.enqueue.mock.calls[0] as [unknown, string])[1]).not.toBe(firstId);
+ });
+
+ it('leaves a route without the flag on the header', async () => {
+ const d = deps();
+ await new IngressService(d).handle({ ...req, headers: { 'x-delivery': 'd-1' } });
+ expect((d.enqueue.mock.calls[0] as [unknown, string])[1]).toBe('d-1');
+ });
+});
+
describe('extractConversationId', () => {
it('returns undefined when no spec is declared', () => {
expect(extractConversationId(undefined, {}, '{}')).toBeUndefined();
diff --git a/src/modules/integration/ingress.service.ts b/src/modules/integration/ingress.service.ts
index 403a21f1d..4ce1d8ce5 100644
--- a/src/modules/integration/ingress.service.ts
+++ b/src/modules/integration/ingress.service.ts
@@ -164,7 +164,10 @@ export class IngressService {
// Other schemes retain the existing x-delivery/body-hash behavior for compatibility.
const defaultDedupHeader = route.signature.scheme === 'standard-webhooks' ? 'webhook-id' : 'x-delivery';
const dedupHeader = (route.dedupHeader ?? route.signature.dedupHeader ?? defaultDedupHeader).toLowerCase();
- const deliveryId = req.headers[dedupHeader] ?? deriveDeliveryId(req);
+ // A route that declares dedupOn: 'body' keys retries on the raw body: its provider mints a fresh
+ // delivery id per attempt, so trusting the header would let every retry through as new.
+ const deliveryId =
+ route.dedupOn === 'body' ? deriveDeliveryId(req) : (req.headers[dedupHeader] ?? deriveDeliveryId(req));
// Provider request headers persist with the event (redrive/debugging); credentials must not.
// Signature headers are re-derivable, auth material is not — redact before the first write.
// A shared-secret route carries the instance secret itself in its declared header.