feat(webhook): optional HMAC-SHA256 request signing

vklimontovich · vklimontovich · commit 7312ab264123 · 2026-07-09T14:55:30.000+03:00
Add optional signing to the webhook destination. When a signing secret is
set, each request is signed with HMAC-SHA256 and the hex signature is sent
in a configurable header (default `Jitsu-Signature`).

Replay protection is on by default: the unix-seconds timestamp is folded
into the signed payload (HMAC over `&lt;timestamp&gt;.&lt;body&gt;`) and sent in a
companion `&lt;header&gt;-Timestamp` header, so the receiver can reject stale
requests. It can be turned off to sign the raw body only.
diff --git a/libs/destination-functions/__tests__/webhook-destination.test.ts b/libs/destination-functions/__tests__/webhook-destination.test.ts
@@ -0,0 +1,53 @@
+import { createHmac } from "crypto";
+import { afterAll, afterEach, beforeAll, expect, test } from "vitest";
+import { http, HttpResponse } from "msw";
+import { setupServer } from "msw/node";
+import { AnalyticsServerEvent } from "@jitsu/protocols/analytics";
+import { testJitsuFunction } from "./lib/testing-lib";
+import WebhookDestination from "../src/functions/webhook-destination";
+import { WebhookDestinationConfig } from "../src/meta";
+
+// MSW intercepts the real fetch so we assert on the actual signed request.
+const url = "http://webhook.test.local/hook";
+const secret = "super-secret-key";
+const server = setupServer();
+
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+// Runs the webhook destination once and returns the signature headers + sent body.
+async function sign(
+  config: Partial<WebhookDestinationConfig>
+): Promise<{ signature: string; timestamp: string | null; body: string }> {
+  let captured: { signature: string; timestamp: string | null; body: string } | undefined;
+  server.use(
+    http.post(url, async ({ request }) => {
+      captured = {
+        signature: request.headers.get("Jitsu-Signature") ?? "",
+        timestamp: request.headers.get("Jitsu-Signature-Timestamp"),
+        body: await request.text(),
+      };
+      return HttpResponse.text("ok");
+    })
+  );
+  await testJitsuFunction<WebhookDestinationConfig>({
+    func: WebhookDestination,
+    config: { url, method: "POST", signatureSecret: secret, ...config } as WebhookDestinationConfig,
+    events: [{ type: "track", event: "test_event", messageId: "m1" } as AnalyticsServerEvent],
+  });
+  if (!captured) throw new Error("webhook was never called");
+  return captured;
+}
+
+test("signs timestamp + body and sends a timestamp header by default", async () => {
+  const { signature, timestamp, body } = await sign({});
+  expect(timestamp).toMatch(/^\d+$/);
+  expect(signature).toBe(createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex"));
+});
+
+test("signs the body only and omits the timestamp header when replay protection is off", async () => {
+  const { signature, timestamp, body } = await sign({ signatureIncludeTimestamp: false });
+  expect(timestamp).toBeNull();
+  expect(signature).toBe(createHmac("sha256", secret).update(body).digest("hex"));
+});
diff --git a/libs/destination-functions/package.json b/libs/destination-functions/package.json
@@ -28,6 +28,7 @@
     "@types/node": "catalog:",
     "@vitest/ui": "catalog:",
     "json5": "^2.1.0",
+    "msw": "^2.15.0",
     "vitest": "catalog:",
     "vite": "^6.4.3"
   },
diff --git a/libs/destination-functions/src/functions/webhook-destination.ts b/libs/destination-functions/src/functions/webhook-destination.ts
@@ -1,3 +1,4 @@
+import { createHmac } from "crypto";
 import { JitsuFunction } from "@jitsu/protocols/functions";
 import { HTTPError, RetryError } from "@jitsu/functions-lib";
 import type { AnalyticsServerEvent } from "@jitsu/protocols/analytics";
@@ -79,6 +80,19 @@ const WebhookDestination: JitsuFunction<AnalyticsServerEvent, WebhookDestination
         payload = JSON.stringify(event);
       }
       const headers = ctx.props.headers || [];
+      const signatureHeaders: Record<string, string> = {};
+      if (ctx.props.signatureSecret) {
+        const headerName = ctx.props.signatureHeader || "Jitsu-Signature";
+        if (ctx.props.signatureIncludeTimestamp ?? true) {
+          const t = Math.floor(Date.now() / 1000);
+          signatureHeaders[headerName] = createHmac("sha256", ctx.props.signatureSecret)
+            .update(`${t}.${payload}`)
+            .digest("hex");
+          signatureHeaders[`${headerName}-Timestamp`] = String(t);
+        } else {
+          signatureHeaders[headerName] = createHmac("sha256", ctx.props.signatureSecret).update(payload).digest("hex");
+        }
+      }
       const res = await ctx.fetch(ctx.props.url, {
         method: ctx.props.method || "POST",
         body: payload,
@@ -88,6 +102,7 @@ const WebhookDestination: JitsuFunction<AnalyticsServerEvent, WebhookDestination
             const [key, value] = header.split(":");
             return { ...res, [key]: value };
           }, {}),
+          ...signatureHeaders,
         },
       });
       if (!res.ok) {
diff --git a/libs/destination-functions/src/meta.ts b/libs/destination-functions/src/meta.ts
@@ -47,6 +47,24 @@ export const WebhookDestinationConfig = z.object({
     .describe(
       "Payload Template::Template for the webhook payload. The following macros are supported:<ul><li><code>{{ EVENT }}</code> - event json object for stream mode or batches with size=1</li><li><code>{{ EVENTS }}</code> - for batch mode - json array of events</li><li><code>{{ EVENTS_COUNT }}</code> - count of events in batch</li><li><code>{{ NAME }}</code> - event name</li><li><code>{{ env.VAR_NAME }}</code> - value of VAR_NAME environment variable</li></ul>"
     ),
+  signatureSecret: z
+    .string()
+    .optional()
+    .describe(
+      "Signing Secret::If set, every request is signed with <code>HMAC-SHA256</code> using this secret and the hex signature is sent in a header (see below). Your receiver recomputes the same HMAC and compares it to reject forged or tampered requests. Leave empty to disable signing."
+    ),
+  signatureHeader: z
+    .string()
+    .optional()
+    .default("Jitsu-Signature")
+    .describe("Signature Header::Name of the header carrying the signature. Only used when a signing secret is set."),
+  signatureIncludeTimestamp: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe(
+      "Replay Protection::When enabled (recommended), the request timestamp (unix seconds) is folded into the signed payload — the HMAC is computed over <code>&lt;timestamp&gt;.&lt;body&gt;</code> — and sent in a companion <code>&lt;Signature Header&gt;-Timestamp</code> header. Your receiver can then reject requests with an old timestamp to block replays of a captured, still-valid request. When disabled, only the raw body is signed and no timestamp header is sent: simpler to verify, but a captured request stays valid forever. Only used when a signing secret is set."
+    ),
 });
 
 export type WebhookDestinationConfig = z.infer<typeof WebhookDestinationConfig>;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/webapps/console/lib/schema/destinations.tsx b/webapps/console/lib/schema/destinations.tsx
