Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(webhook): salt session.reconnect_loop keys per occurrence

Yudhi Armyndharisbad8f8c51b9e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3ce9b6e97..88cc55802 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- A session whose automatic reconnect fails to relaunch the engine (a network, DNS or browser launch error) keeps retrying with backoff instead of stopping in `failed` until restarted by hand; an authentication failure or a stale browser profile still ends in `failed` ([#1580](https://github.com/rmyndharis/OpenWA/issues/1580)).
- A session that runs out of reconnect attempts fires the `session:error` plugin hook when it lands in `failed`.
- An explicit `maxReconnectAttempts` is honoured and the reconnect delay is capped at 5 minutes; the budget used to restart once the backoff passed 5 minutes, so the limit was never reached and the documented 1-hour cap never applied.
+- `session.reconnect_loop` webhooks carry an idempotency key salted per occurrence, so an alert from a later outage that reaches the same attempt count is no longer deduplicated onto the earlier one or left without a delivery record.
## [0.23.5] - 2026-09-14
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 2f1f435ac..3470be653 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -6908,6 +6908,7 @@ Every delivery includes:
- `session.status`: `sess_{sessionId}_{status}_{occurredAt}`
- `session.authenticated`: `auth_{sessionId}_{hash(data)}_{occurredAt}`
- `session.disconnected`: `disc_{sessionId}_{hash(reason)}_{occurredAt}`
+- `session.reconnect_loop`: `loop_{sessionId}_{attempts}_{occurredAt}`
- `group.join` / `group.leave`: `grp_{groupId}_{hash(participantIds)}_{join|leave}_{occurredAt}`
- `group.update`: `grp_{groupId}_update_{hash(changes)}_{occurredAt}`
- `group.join_request`: `grp_{groupId}_{hash(participantIds)}_join_request_{occurredAt}` (salted like `group.join` — a rejected user can legitimately ask again)
diff --git a/src/modules/webhook/utils/idempotency.util.spec.ts b/src/modules/webhook/utils/idempotency.util.spec.ts
index 37b956048..41b1f7def 100644
--- a/src/modules/webhook/utils/idempotency.util.spec.ts
+++ b/src/modules/webhook/utils/idempotency.util.spec.ts
@@ -131,6 +131,16 @@ describe('Idempotency Utils', () => {
expect(a).toBe(b);
});
+ // Once the backoff reaches its cap, a later outage that loops to the same attempt count dispatches
+ // a byte-identical payload; the second alert is news and must not dedupe onto the first.
+ it('salts session.reconnect_loop keys per occurrence and keeps them retry-stable', () => {
+ const payload = { sessionId: 'A', attempts: 10, nextDelayMs: 300_000 };
+ const first = generateIdempotencyKey('session.reconnect_loop', payload, '2026-09-01T00:00:00.000Z');
+ const later = generateIdempotencyKey('session.reconnect_loop', payload, '2026-09-01T06:00:00.000Z');
+ expect(first).not.toBe(later);
+ expect(generateIdempotencyKey('session.reconnect_loop', { ...payload }, '2026-09-01T00:00:00.000Z')).toBe(first);
+ });
+
it('does not salt message-event keys with the occurrence time (content-based dedup preserved)', () => {
const a = generateIdempotencyKey(
'message.ack',
diff --git a/src/modules/webhook/utils/idempotency.util.ts b/src/modules/webhook/utils/idempotency.util.ts
index 302e7a5c2..d3771c933 100644
--- a/src/modules/webhook/utils/idempotency.util.ts
+++ b/src/modules/webhook/utils/idempotency.util.ts
@@ -88,6 +88,12 @@ export function generateIdempotencyKey(event: string, data: Record<string, unkno
// always sends 'logged out'), which would otherwise collapse every disconnect onto one key.
return `disc_${toStr(data.sessionId)}_${hashData({ reason: data.reason })}${occurrence}`;
+ case 'session.reconnect_loop':
+ // Salted per occurrence: once the backoff hits its cap, a later outage that loops to the same
+ // attempt count produces a byte-identical payload, and that second alert must not collapse
+ // onto the first at the receiver or in the outbox and failure tables.
+ return `loop_${toStr(data.sessionId)}_${toStr(data.attempts)}${occurrence}`;
+
case 'session.restriction':
// Keyed on what changed (`kind` is null when a restriction is lifted) and salted per
// occurrence: an account that is restricted, freed and restricted again for the same cause