Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.ts
index 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, unkno
case '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, unkno
case '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, unkno
case '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.ts
index 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.ts
index 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