Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(webhook): send a fresh idempotency key on every test delivery

Yudhi Armyndharis3b3c5e294d45
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index cf7148fa2..9b6eb9bba 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -4743,6 +4743,8 @@ Send a synthetic test payload to the webhook URL and report the result. No reque
On a reachable endpoint the response is `{ success: <response.ok>, statusCode: <response.status> }` — so a non-2xx target returns `200` HTTP with `success: false` and the target's `statusCode`. On an SSRF/timeout/network error the response is `{ "success": false, "error": "<message>" }`. The endpoint never throws on delivery failure; the failure is reflected in the body, not the HTTP status. The test POST sends `{ "event": "test", ... }` with headers `Content-Type`, `User-Agent: OpenWA-Webhook/1.0.0`, `X-OpenWA-Event: test`, `X-OpenWA-Idempotency-Key`, `X-OpenWA-Delivery-Id`, `X-OpenWA-Retry-Count: 0`, and `X-OpenWA-Signature` when a secret is set. Timeout defaults to 10000 ms (`webhook.timeout` config).
+Every test call carries a fresh `X-OpenWA-Idempotency-Key` (`test_<deliveryId>_<webhookId>`), so a receiver that dedups on it runs its handler for each test.
+
**Errors:** `401` missing/invalid API key · `403` insufficient role · `404` webhook not found in this session
#### DELETE /api/sessions/:sessionId/webhooks/:id
diff --git a/src/modules/webhook/webhook.service.spec.ts b/src/modules/webhook/webhook.service.spec.ts
index 77d70390a..2d9758259 100644
--- a/src/modules/webhook/webhook.service.spec.ts
+++ b/src/modules/webhook/webhook.service.spec.ts
@@ -479,6 +479,23 @@ describe('WebhookService', () => {
timeoutSpy.mockRestore();
});
+ // Receivers dedup on X-OpenWA-Idempotency-Key. A key that repeats per webhook makes every test
+ // after the first a silent duplicate that reports success while the handler never runs.
+ it('test() sends a fresh idempotency key on every call, suffixed with the webhook id', async () => {
+ const webhook = createMockWebhook({ events: ['message.received'] });
+ (repository.findOne as jest.Mock).mockResolvedValue(webhook);
+
+ await service.test('sess-1', webhook.id);
+ await service.test('sess-1', webhook.id);
+
+ const keys = (mockFetch.mock.calls as Array<[string, { headers: Record<string, string> }]>).map(
+ ([, init]) => init.headers['X-OpenWA-Idempotency-Key'],
+ );
+ expect(keys).toHaveLength(2);
+ expect(keys[0]).not.toBe(keys[1]);
+ for (const key of keys) expect(key.endsWith(`_${webhook.id}`)).toBe(true);
+ });
+
// A literal link-local IP is rejected synchronously by the SSRF guard before any fetch/DNS, so this
// is fully offline. The raw SsrfBlockedError message names the resolved internal IP — an SSRF
// disclosure oracle — so the test() response must surface the generic constant instead.
diff --git a/src/modules/webhook/webhook.service.ts b/src/modules/webhook/webhook.service.ts
index e9448d52a..3efd1517d 100644
--- a/src/modules/webhook/webhook.service.ts
+++ b/src/modules/webhook/webhook.service.ts
@@ -9,7 +9,7 @@ import { CreateWebhookDto, UpdateWebhookDto } from './dto';
import { createLogger } from '../../common/services/logger.service';
import { resolveSessionScope } from '../../common/security/session-scope';
import { ListOptions, resolveListWindow } from '../../common/utils/paginate';
-import { generateIdempotencyKey, generateDeliveryId } from './utils/idempotency.util';
+import { generateDeliveryId } from './utils/idempotency.util';
import {
assertSafeFetchUrl,
withSafeFetch,
@@ -244,12 +244,15 @@ export class WebhookService implements OnModuleInit, OnModuleDestroy {
async test(sessionId: string, webhookId: string): Promise<{ success: boolean; statusCode?: number; error?: string }> {
const webhook = await this.findOne(sessionId, webhookId);
+ // Every test is a new event: a key derived from the webhook alone repeats on every call, so a
+ // receiver that dedups on it acknowledges the second test without running its handler.
+ const deliveryId = generateDeliveryId();
const testPayload: WebhookPayload = {
event: 'test',
timestamp: new Date().toISOString(),
sessionId,
- idempotencyKey: generateIdempotencyKey('test', { webhookId: webhook.id }),
- deliveryId: generateDeliveryId(),
+ idempotencyKey: `test_${deliveryId}_${webhook.id}`,
+ deliveryId,
data: {
message: 'This is a test webhook from OpenWA',
webhookId: webhook.id,