Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(webhook): give each recurring event occurrence its own key
Yudhi Armyndharisacf151cd24ff
diff --git a/src/modules/webhook/utils/idempotency.util.ts b/src/modules/webhook/utils/idempotency.util.tsindex c9449f333..372a57c5f 100644--- a/src/modules/webhook/utils/idempotency.util.ts+++ b/src/modules/webhook/utils/idempotency.util.ts@@ -26,15 +26,15 @@ function hashData(data: Record<string, unknown>): string {* @remarks* Stable message keys are content-based (keyed on the unique message id), so two deliveries of the* same logical message dedupe. Recurring events (message edits/reactions and session lifecycle- * transitions) can repeat with identical content, so they are salted with `occurredAt` (captured ONCE+ * transitions) can repeat with identical content, so they are salted with `occurrenceId` (minted ONCE* per dispatch and reused across retries): distinct occurrences get distinct keys while retries of* the same occurrence stay stable.*- * @param occurredAt - ISO timestamp captured once per dispatch; salts recurring occurrence keys.+ * @param occurrenceId - Unique id minted once per dispatch; salts recurring occurrence keys.*/-export function generateIdempotencyKey(event: string, data: Record<string, unknown>, occurredAt?: string): string {+export function generateIdempotencyKey(event: string, data: Record<string, unknown>, occurrenceId?: string): string {// Only recurring occurrence keys consume this salt; stable message and QR keys ignore it.- const occurrence = occurredAt ? `_${occurredAt}` : '';+ const occurrence = occurrenceId ? `_${occurrenceId}` : '';switch (event) {case 'message.received':case 'message.sent':@@ -62,7 +62,7 @@ export function generateIdempotencyKey(event: string, data: Record<string, unknocase 'message.edited':// Editing the same message multiple times should produce different idempotency keys.- // Salt with occurredAt (captured once per dispatch, reused across retries) so distinct occurrences+ // Salt with occurrenceId (minted once per dispatch, reused across retries) so distinct occurrences// get distinct keys, while retries of the same delivery stay stable.return `edit_${toStr(data.sessionId)}_${toStr(data.messageId)}${occurrence}`;@@ -70,7 +70,7 @@ export function generateIdempotencyKey(event: string, data: Record<string, unkno// A reaction carries no unique id and is a read-modify-write of the message's reactions map; the// same sender can re-apply the same emoji over time (π β remove β π). Keying on// (sender, target message) alone would collapse a genuine re-reaction onto the earlier one, so salt- // with occurredAt (captured once per dispatch, reused across retries): distinct occurrences get+ // with occurrenceId (minted once per dispatch, reused across retries): distinct occurrences get// distinct keys while retries of the same delivery stay stable.return `react_${toStr(data.sessionId)}_${toStr(data.messageId)}_${toStr(data.senderId)}${occurrence}`;@@ -130,7 +130,7 @@ export function generateIdempotencyKey(event: string, data: Record<string, unknocase 'group.join':// A membership change carries no unique id and repeats with identical content (the same user// leaves and rejoins the same group). Key on the affected participants and salt with- // occurredAt (captured once per dispatch, reused across retries) so a genuine re-join is not+ // occurrenceId (minted once per dispatch, reused across retries) so a genuine re-join is not// deduped onto the earlier delivery.return `grp_${toStr(data.groupId)}_${hashData({ participants: data.participantIds })}_join${occurrence}`;@@ -152,7 +152,7 @@ export function generateIdempotencyKey(event: string, data: Record<string, unknocase 'call.received':// A call id is unique per call, so keying on (session, callId) gives each occurrence a- // distinct key with no occurredAt salt, while retries of the same dispatch regenerate the+ // distinct key with no occurrenceId salt, while retries of the same dispatch regenerate the// same key (same stability contract as the message.* keys). Scoped by sessionId like `msg_`.return `call_${toStr(data.sessionId)}_${toStr(data.callId)}`;diff --git a/src/modules/webhook/webhook-delivery.service.spec.ts b/src/modules/webhook/webhook-delivery.service.spec.tsindex df09afdba..abf035fb6 100644--- a/src/modules/webhook/webhook-delivery.service.spec.ts+++ b/src/modules/webhook/webhook-delivery.service.spec.ts@@ -79,7 +79,11 @@ describe('WebhookDeliveryService', () => {let hookManager: jest.Mocked<Partial<HookManager>>;let webhookQueue: jest.Mocked<Record<string, jest.Mock>>;let lidStore: { getCached: jest.Mock; resolveLid: jest.Mock; phonesForLidsPersisted: jest.Mock };- let outboxService: { open: jest.Mock; close: jest.Mock; markQueued: jest.Mock };+ let outboxService: {+ open: jest.MockedFunction<WebhookOutboxService['open']>;+ close: jest.Mock;+ markQueued: jest.Mock;+ };let insertedFailures: Array<Partial<WebhookDeliveryFailure>>;beforeEach(async () => {@@ -204,6 +208,41 @@ describe('WebhookDeliveryService', () => {service = module.get<WebhookDeliveryService>(WebhookDeliveryService);});+ it.each(['message.edited', 'message.reaction', 'session.status'])(+ 'keeps separate %s occurrences distinct within one clock millisecond',+ async event => {+ const clock = jest.spyOn(Date.prototype, 'toISOString').mockReturnValue('2026-10-25T12:00:00.000Z');+ (repository.find as jest.Mock).mockResolvedValue([createMockWebhook({ events: [event] })]);+ (hookManager.execute as jest.Mock).mockResolvedValue({ continue: true, data: {} });+ (undiciFetch as jest.Mock).mockResolvedValue({ ok: true, status: 200 });+ const data = { messageId: 'same-message', senderId: '[email protected]', status: 'ready' };+ try {+ await service.dispatch('sess-1', event, { ...data, body: 'first', reaction: 'a' });+ await service.dispatch('sess-1', event, { ...data, body: 'second', reaction: 'b' });+ const keys = outboxService.open.mock.calls.map(([row]) => row.idempotencyKey);+ expect(keys).toHaveLength(2);+ expect(new Set(keys).size).toBe(2);+ } finally {+ clock.mockRestore();+ (undiciFetch as jest.Mock).mockReset();+ }+ },+ );++ it('retains a stable key for duplicate message deliveries in one clock millisecond', async () => {+ (repository.find as jest.Mock).mockResolvedValue([createMockWebhook()]);+ (hookManager.execute as jest.Mock).mockResolvedValue({ continue: true, data: {} });+ (undiciFetch as jest.Mock).mockResolvedValue({ ok: true, status: 200 });+ try {+ for (let i = 0; i < 2; i++) await service.dispatch('sess-1', 'message.received', { id: 'same-message' });+ const keys = outboxService.open.mock.calls.map(([row]) => row.idempotencyKey);+ expect(keys).toHaveLength(2);+ expect(new Set(keys).size).toBe(1);+ } finally {+ (undiciFetch as jest.Mock).mockReset();+ }+ });+// The drain bound at shutdown must cover the per-delivery timeout, or a delivery that takes nearly// the full timeout is abandoned at shutdown. The defaults already cross (drain 5s < timeout 10s),// so the warning is the only signal an operator gets that their config silently truncates deliveries.diff --git a/src/modules/webhook/webhook-delivery.service.ts b/src/modules/webhook/webhook-delivery.service.tsindex cb26f9266..fba9c4901 100644--- a/src/modules/webhook/webhook-delivery.service.ts+++ b/src/modules/webhook/webhook-delivery.service.ts@@ -5,6 +5,7 @@ import { ConfigService } from '@nestjs/config';import { InjectQueue } from '@nestjs/bullmq';import { Queue } from 'bullmq';import { setTimeout } from 'node:timers/promises';+import { randomUUID } from 'node:crypto';import { Webhook } from './entities/webhook.entity';import { WebhookOutboxService, type ReplayableDelivery } from './webhook-outbox.service';import { WebhookDeliveryFailure } from './entities/webhook-delivery-failure.entity';@@ -434,11 +435,10 @@ export class WebhookDeliveryService implements OnModuleInit, OnModuleDestroy {data,);- // Base idempotency key for this event occurrence. occurredAt is captured once here and reused for- // every retry of this dispatch, so recurring lifecycle events get a distinct-per-occurrence key- // while retries of the same event stay stable. It is salted PER WEBHOOK below.- const occurredAt = new Date().toISOString();- const baseIdempotencyKey = generateIdempotencyKey(event, { ...data, sessionId }, occurredAt);+ // Base idempotency key for this event occurrence. The occurrence id is minted once here and reused for+ // every retry of this dispatch, so recurring lifecycle events get a distinct-per-occurrence key (even two+ // within one clock millisecond) while retries of the same event stay stable. It is salted PER WEBHOOK below.+ const baseIdempotencyKey = generateIdempotencyKey(event, { ...data, sessionId }, randomUUID());// Fan-out amplification bound: shed an over-cap inline media blob ONCE here, before the// per-webhook structuredClone below, so N matching webhooks (and the queued jobs retained in