// AK-P16d · route contract for the public PandaDoc BYOK webhook: HMAC-gated // processing, quiet 200-ack for anything unverifiable (mirrors the calendar // webhook posture — probing must not reveal tenants or connections). import { createHmac } from "node:crypto"; import { beforeEach, describe, expect, it, vi } from "vitest"; const mocks = vi.hoisted(() => ({ runWithConnectionCredentials: vi.fn(), handlePandaDocWebhook: vi.fn(), })); vi.mock("~/utils/integrations/appsEngineService.server", () => ({ runWithConnectionCredentials: mocks.runWithConnectionCredentials, })); vi.mock("~/modules/signature/services/signatureService.server", () => ({ handlePandaDocWebhook: mocks.handlePandaDocWebhook, })); import { action } from "./webhooks.pandadoc.$tenantId.$connectionId"; const SHARED_KEY = "shared_key_1"; const BODY = JSON.stringify({ event: "document.completed", data: { id: "pd_doc_1" } }); function sign(body: string, key: string): string { return createHmac("sha256", key).update(body).digest("hex"); } function webhookRequest(options: { body?: string; signature?: string | null } = {}): Request { const body = options.body ?? BODY; const signature = options.signature === undefined ? sign(body, SHARED_KEY) : options.signature; const url = new URL("https://app.example.test/webhooks/pandadoc/tenant_1/connection_1"); if (signature !== null) url.searchParams.set("signature", signature); return new Request(url, { method: "POST", body }); } function act(request: Request): Promise { return action({ request, params: { tenantId: "tenant_1", connectionId: "connection_1" }, context: undefined } as never); } beforeEach(() => { vi.clearAllMocks(); // Default: connection exists and exposes the shared key to the callback. mocks.runWithConnectionCredentials.mockImplementation( async (_input: unknown, callback: (credentials: Record) => Promise) => callback({ apiKey: "api_key_1", webhookSharedKey: SHARED_KEY }), ); mocks.handlePandaDocWebhook.mockResolvedValue({ ok: true }); }); describe("PandaDoc BYOK webhook", () => { it("processes a correctly signed payload against the pandadoc connection", async () => { const response = await act(webhookRequest()); expect(response.status).toBe(200); expect(mocks.runWithConnectionCredentials).toHaveBeenCalledWith( { tenantId: "tenant_1", connectionId: "connection_1", expectedAppId: "pandadoc-byok" }, expect.any(Function), ); expect(mocks.handlePandaDocWebhook).toHaveBeenCalledWith({ tenantId: "tenant_1", rawBody: BODY, verified: true }); }); it("acks without processing when the signature is missing or wrong", async () => { const missing = await act(webhookRequest({ signature: null })); expect(missing.status).toBe(200); expect(mocks.runWithConnectionCredentials).not.toHaveBeenCalled(); const wrong = await act(webhookRequest({ signature: sign(BODY, "other_key") })); expect(wrong.status).toBe(200); expect(mocks.handlePandaDocWebhook).not.toHaveBeenCalled(); }); it("acks without leaking when the connection is unknown or unavailable", async () => { mocks.runWithConnectionCredentials.mockRejectedValue(new Error("not found")); const response = await act(webhookRequest()); expect(response.status).toBe(200); expect(mocks.handlePandaDocWebhook).not.toHaveBeenCalled(); }); it("rejects non-POST methods", async () => { const response = await action({ request: new Request("https://app.example.test/webhooks/pandadoc/tenant_1/connection_1", { method: "PUT", body: BODY }), params: { tenantId: "tenant_1", connectionId: "connection_1" }, context: undefined, } as never); expect(response.status).toBe(405); }); });