Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

perf(webhooks): skip message.receipt dispatch when no webhook names it

KGMA74066df614448f
diff --git a/src/modules/webhook/webhook-delivery.service.spec.ts b/src/modules/webhook/webhook-delivery.service.spec.ts
index c39f2aab3..e28c70d55 100644
--- a/src/modules/webhook/webhook-delivery.service.spec.ts
+++ b/src/modules/webhook/webhook-delivery.service.spec.ts
@@ -1025,6 +1025,86 @@ describe('WebhookDeliveryService', () => {
expect(mockFetch).not.toHaveBeenCalled();
});
+ describe('opt-in event gate (message.receipt)', () => {
+ const receipt = { id: 'OUT1', participant: '[email protected]', status: 'read' };
+ // The gate's lookup selects the events column only; dispatch's own lookup reads whole rows.
+ const fullRowLookups = (): unknown[][] =>
+ ((repository.find as jest.Mock).mock.calls as unknown[][]).filter(
+ ([opts]) => !(opts as { select?: unknown } | undefined)?.select,
+ );
+
+ it('never reaches the dispatch lookup when no active webhook names it, and reads once per burst', async () => {
+ (repository.find as jest.Mock).mockResolvedValue([createMockWebhook({ events: ['message.received', '*'] })]);
+
+ await Promise.all(Array.from({ length: 2000 }, () => service.dispatch('sess-1', 'message.receipt', receipt)));
+
+ expect(repository.find).toHaveBeenCalledTimes(1);
+ expect(fullRowLookups()).toHaveLength(0);
+ expect(mockFetch).not.toHaveBeenCalled();
+ });
+
+ it('delivers when an active webhook names it', async () => {
+ (repository.find as jest.Mock).mockResolvedValue([createMockWebhook({ events: ['message.receipt'] })]);
+
+ await service.dispatch('sess-1', 'message.receipt', receipt);
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not gate events a wildcard covers', async () => {
+ (repository.find as jest.Mock).mockResolvedValue([createMockWebhook({ events: ['message.received'] })]);
+
+ await service.dispatch('sess-1', 'message.received', {});
+
+ expect(repository.find).toHaveBeenCalledTimes(1);
+ expect(fullRowLookups()).toHaveLength(1);
+ });
+
+ it('reads again after an invalidation', async () => {
+ (repository.find as jest.Mock).mockResolvedValue([createMockWebhook({ events: ['message.received'] })]);
+ await service.dispatch('sess-1', 'message.receipt', receipt);
+ expect(mockFetch).not.toHaveBeenCalled();
+
+ (repository.find as jest.Mock).mockResolvedValue([createMockWebhook({ events: ['message.receipt'] })]);
+ service.invalidateOptInSubscriptions('sess-1');
+ await service.dispatch('sess-1', 'message.receipt', receipt);
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ });
+
+ it('reads again once the cached answer expires (a change made on another instance)', async () => {
+ const now = jest.spyOn(Date, 'now').mockReturnValue(1_000_000);
+ try {
+ (repository.find as jest.Mock).mockResolvedValue([createMockWebhook({ events: ['message.received'] })]);
+ await service.dispatch('sess-1', 'message.receipt', receipt);
+
+ (repository.find as jest.Mock).mockResolvedValue([createMockWebhook({ events: ['message.receipt'] })]);
+ now.mockReturnValue(1_000_000 + 4_999);
+ await service.dispatch('sess-1', 'message.receipt', receipt);
+ expect(mockFetch).not.toHaveBeenCalled();
+
+ now.mockReturnValue(1_000_000 + 5_000);
+ await service.dispatch('sess-1', 'message.receipt', receipt);
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ } finally {
+ now.mockRestore();
+ }
+ });
+
+ it('lets the event through on a failed lookup, without caching the failure', async () => {
+ (repository.find as jest.Mock).mockRejectedValueOnce(new Error('db down'));
+ (repository.find as jest.Mock).mockResolvedValue([createMockWebhook({ events: ['message.receipt'] })]);
+
+ await service.dispatch('sess-1', 'message.receipt', receipt);
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ await service.dispatch('sess-1', 'message.receipt', receipt);
+
+ const gateLookups = (repository.find as jest.Mock).mock.calls.length - fullRowLookups().length;
+ expect(gateLookups).toBe(2);
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+ });
+
it('should skip dispatch when plugin cancels via hook', async () => {
const webhook = createMockWebhook({ events: ['message.received'] });
(repository.find as jest.Mock).mockResolvedValue([webhook]);
diff --git a/src/modules/webhook/webhook-delivery.service.ts b/src/modules/webhook/webhook-delivery.service.ts
index e8e2649ce..242985d2a 100644
--- a/src/modules/webhook/webhook-delivery.service.ts
+++ b/src/modules/webhook/webhook-delivery.service.ts
@@ -26,7 +26,7 @@ import { redactSsrfError } from '../../common/security/ssrf-guard';
import { HookManager } from '../../core/hooks';
import { ConcurrencyLimiter } from '../../common/utils/concurrency-limiter';
import { isWebhookBeforeResult } from '../../core/hooks/hook-results';
-import { subscriptionCoversEvent } from '../../common/utils/wildcard-events';
+import { WILDCARD_EXCLUDED_EVENTS, subscriptionCoversEvent } from '../../common/utils/wildcard-events';
export interface WebhookPayload {
event: string;
@@ -71,6 +71,13 @@ const DEFAULT_WEBHOOK_MAX_PAYLOAD_BYTES = 1024 * 1024;
*/
const DEFAULT_WEBHOOK_SHUTDOWN_DRAIN_MS = 5000;
+/**
+ * How long a session's answer to "which opt-in events does an active webhook name" is reused. Writes
+ * through WebhookService drop the answer at once on this node; a write on another instance (Redis
+ * deployment), or one that bypasses WebhookService, is picked up when it expires.
+ */
+const OPT_IN_SUBSCRIPTIONS_TTL_MS = 5000;
+
/**
* The result of one delivery attempt. Reported, not thrown: every delivery failure below is already
* handled in place, so a try/catch cannot tell a delivered event from a dead-lettered one. The one
@@ -155,6 +162,11 @@ export class WebhookDeliveryService implements OnModuleInit, OnModuleDestroy {
* not replayed alongside itself.
*/
private readonly locallyPending = new Map<string, number>();
+ /**
+ * Per session, the opt-in events (WILDCARD_EXCLUDED_EVENTS) that at least one active webhook names.
+ * The promise is cached, not its result, so a burst of receipts on a cold entry shares one lookup.
+ */
+ private readonly optInSubscriptions = new Map<string, { events: Promise<ReadonlySet<string>>; expiresAt: number }>();
constructor(
@InjectRepository(Webhook, 'data')
@@ -246,6 +258,9 @@ export class WebhookDeliveryService implements OnModuleInit, OnModuleDestroy {
}
async dispatch(sessionId: string, event: string, data: Record<string, unknown>): Promise<void> {
+ // An opt-in event fires per recipient (about 2,000 per message to a 1,000-member group): skip it
+ // before the per-dispatch webhook read when no active webhook of the session names it.
+ if (WILDCARD_EXCLUDED_EVENTS.includes(event) && !(await this.sessionNamesOptInEvent(sessionId, event))) return;
const webhooks = await this.loadActiveWebhooks(sessionId, event);
const matchingWebhooks = this.filterMatchingWebhooks(webhooks, event, data);
@@ -272,6 +287,50 @@ export class WebhookDeliveryService implements OnModuleInit, OnModuleDestroy {
await Promise.allSettled(matchingWebhooks.map(webhook => this.dispatchWithLimit(webhook, baseIdempotencyKey, ctx)));
}
+ /**
+ * Drop the session's cached opt-in subscriptions. WebhookService calls this after every webhook
+ * create, update and delete, so a change made on this node applies to the next event.
+ */
+ invalidateOptInSubscriptions(sessionId: string): void {
+ this.optInSubscriptions.delete(sessionId);
+ }
+
+ /**
+ * Whether an active webhook of the session names `event`, read at most once per
+ * OPT_IN_SUBSCRIPTIONS_TTL_MS. A failed lookup is not cached and lets the event through, so
+ * dispatch's own lookup reports the failure as before.
+ */
+ private async sessionNamesOptInEvent(sessionId: string, event: string): Promise<boolean> {
+ const now = Date.now();
+ let entry = this.optInSubscriptions.get(sessionId);
+ if (!entry || entry.expiresAt <= now) {
+ const created = {
+ events: this.webhookRepository
+ .find({ select: { id: true, events: true }, where: { sessionId, active: true } })
+ .then(rows => {
+ const named = new Set<string>();
+ for (const row of rows) {
+ if (!Array.isArray(row.events)) continue;
+ for (const e of row.events) if (WILDCARD_EXCLUDED_EVENTS.includes(e)) named.add(e);
+ }
+ return named;
+ }),
+ expiresAt: now + OPT_IN_SUBSCRIPTIONS_TTL_MS,
+ };
+ // Identity check: an invalidation (or a newer entry) since this lookup started must not be undone.
+ created.events.catch(() => {
+ if (this.optInSubscriptions.get(sessionId) === created) this.optInSubscriptions.delete(sessionId);
+ });
+ this.optInSubscriptions.set(sessionId, created);
+ entry = created;
+ }
+ try {
+ return (await entry.events).has(event);
+ } catch {
+ return true;
+ }
+ }
+
/**
* Callers fire-and-forget this (`void dispatch(...)`), so a failure looking up webhooks must be
* logged and swallowed here — otherwise it surfaces as an unhandled promise rejection.
diff --git a/src/modules/webhook/webhook.service.spec.ts b/src/modules/webhook/webhook.service.spec.ts
index 1c4e9b12d..f94b0f81c 100644
--- a/src/modules/webhook/webhook.service.spec.ts
+++ b/src/modules/webhook/webhook.service.spec.ts
@@ -471,6 +471,25 @@ describe('WebhookService', () => {
});
});
+ describe('opt-in subscription invalidation', () => {
+ it('drops the cached opt-in subscriptions after a create, an update and a delete', async () => {
+ const delivery = testingModule.get<WebhookDeliveryService>(WebhookDeliveryService);
+ const invalidate = jest.spyOn(delivery, 'invalidateOptInSubscriptions');
+ const webhook = createMockWebhook();
+ (repository.create as jest.Mock).mockReturnValue(webhook);
+ (repository.save as jest.Mock).mockResolvedValue(webhook);
+ (repository.findOne as jest.Mock).mockResolvedValue(webhook);
+ (repository.update as jest.Mock).mockResolvedValue({ affected: 1 });
+ (repository.remove as jest.Mock).mockResolvedValue(webhook);
+
+ await service.create('sess-1', { url: 'https://example.com/webhook', events: ['message.receipt'] });
+ await service.update('sess-1', 'wh-uuid-1', { events: ['message.received'] });
+ await service.delete('sess-1', 'wh-uuid-1');
+
+ expect(invalidate.mock.calls).toEqual([['sess-1'], ['sess-1'], ['sess-1']]);
+ });
+ });
+
// ── dispatch (direct mode — queue disabled) ───────────────────────
describe('delivery-failure retention', () => {
diff --git a/src/modules/webhook/webhook.service.ts b/src/modules/webhook/webhook.service.ts
index d4085fc23..c21b86c92 100644
--- a/src/modules/webhook/webhook.service.ts
+++ b/src/modules/webhook/webhook.service.ts
@@ -204,7 +204,9 @@ export class WebhookService implements OnModuleInit, OnModuleDestroy {
retryCount: dto.retryCount ?? 3,
});
- return this.webhookRepository.save(webhook);
+ const saved = await this.webhookRepository.save(webhook);
+ this.delivery.invalidateOptInSubscriptions(sessionId);
+ return saved;
}
async findBySession(sessionId: string): Promise<Webhook[]> {
@@ -308,6 +310,7 @@ export class WebhookService implements OnModuleInit, OnModuleDestroy {
// re-insert a row a concurrent DELETE removed during the URL check, and write back stale values
// of every column this request did not touch.
const result = await this.webhookRepository.update({ id, sessionId }, patch);
+ this.delivery.invalidateOptInSubscriptions(sessionId);
if (!result.affected) throw new NotFoundException(`Webhook with id '${id}' not found`);
return this.findOne(sessionId, id);
}
@@ -315,6 +318,7 @@ export class WebhookService implements OnModuleInit, OnModuleDestroy {
async delete(sessionId: string, id: string): Promise<void> {
const webhook = await this.findOne(sessionId, id);
await this.webhookRepository.remove(webhook);
+ this.delivery.invalidateOptInSubscriptions(sessionId);
}
async test(sessionId: string, webhookId: string): Promise<{ success: boolean; statusCode?: number; error?: string }> {