Add webhook verification functionality for secure payload validation

jnsdls · jnsdls · commit 09b2a7ef912b · 2025-05-20T16:31:28.000-07:00
diff --git a/.changeset/webhook-verification.md b/.changeset/webhook-verification.md
@@ -0,0 +1,22 @@
+---
+"thirdweb": minor
+---
+
+Added webhook verification functionality to securely verify incoming webhooks from thirdweb. This includes:
+
+- New `Webhook.parse` function to verify webhook signatures and timestamps
+- Support for both `x-payload-signature` and `x-pay-signature` header formats
+- Timestamp verification with configurable tolerance
+- Version 2 webhook payload type support
+
+Example usage:
+```typescript
+import Webhook from "thirdweb/bridge";
+
+const webhook = await Webhook.parse(
+  payload,
+  headers,
+  secret,
+  300 // optional tolerance in seconds
+);
+``` 
diff --git a/packages/thirdweb/src/bridge/Webhook.test.ts b/packages/thirdweb/src/bridge/Webhook.test.ts
@@ -0,0 +1,150 @@
+import { describe, expect, it } from "vitest";
+import { type WebhookPayload, parse } from "./Webhook.js";
+
+describe("parseIncomingWebhook", () => {
+  const secret = "test-secret";
+  const timestamp = Math.floor(Date.now() / 1000).toString();
+  const validPayload: WebhookPayload = {
+    version: 2,
+    data: {
+      transactionId: "tx123",
+      paymentId: "pay123",
+      clientId: "client123",
+      action: "payment",
+      status: "completed",
+      originToken: "ETH",
+      originAmount: "1.0",
+      destinationToken: "0x1234567890123456789012345678901234567890",
+      destinationAmount: "1.0",
+      sender: "0x1234567890123456789012345678901234567890",
+      receiver: "0x1234567890123456789012345678901234567890",
+      type: "transfer",
+      transactions: ["tx1", "tx2"],
+      developerFeeBps: 100,
+      developerFeeRecipient: "0x1234567890123456789012345678901234567890",
+      purchaseData: {},
+    },
+  };
+
+  const payloadString = JSON.stringify(validPayload);
+
+  // Helper function to generate signature
+  const generateSignature = async (timestamp: string, payload: string) => {
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey(
+      "raw",
+      encoder.encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"],
+    );
+
+    const signature = await crypto.subtle.sign(
+      "HMAC",
+      key,
+      encoder.encode(`${timestamp}.${payload}`),
+    );
+
+    return Array.from(new Uint8Array(signature))
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+  };
+
+  it("should successfully verify a valid webhook", async () => {
+    const signature = await generateSignature(timestamp, payloadString);
+    const headers = {
+      "x-payload-signature": signature,
+      "x-timestamp": timestamp,
+    };
+
+    const result = await parse(payloadString, headers, secret);
+    expect(result).toEqual(validPayload);
+  });
+
+  it("should accept alternative header names", async () => {
+    const signature = await generateSignature(timestamp, payloadString);
+    const headers = {
+      "x-pay-signature": signature,
+      "x-pay-timestamp": timestamp,
+    };
+
+    const result = await parse(payloadString, headers, secret);
+    expect(result).toEqual(validPayload);
+  });
+
+  it("should throw error for missing headers", async () => {
+    const headers = {};
+    await expect(parse(payloadString, headers, secret)).rejects.toThrow(
+      "Missing required webhook headers: signature or timestamp",
+    );
+  });
+
+  it("should throw error for invalid signature", async () => {
+    const headers = {
+      "x-payload-signature": "invalid-signature",
+      "x-timestamp": timestamp,
+    };
+
+    await expect(parse(payloadString, headers, secret)).rejects.toThrow(
+      "Invalid webhook signature",
+    );
+  });
+
+  it("should throw error for expired timestamp", async () => {
+    const oldTimestamp = (Math.floor(Date.now() / 1000) - 400).toString(); // 400 seconds old
+    const signature = await generateSignature(oldTimestamp, payloadString);
+    const headers = {
+      "x-payload-signature": signature,
+      "x-timestamp": oldTimestamp,
+    };
+
+    await expect(parse(payloadString, headers, secret, 300)).rejects.toThrow(
+      "Webhook timestamp is too old",
+    );
+  });
+
+  it("should throw error for invalid JSON payload", async () => {
+    const invalidPayload = "invalid-json";
+    const signature = await generateSignature(timestamp, invalidPayload);
+    const headers = {
+      "x-payload-signature": signature,
+      "x-timestamp": timestamp,
+    };
+
+    await expect(parse(invalidPayload, headers, secret)).rejects.toThrow(
+      "Invalid webhook payload: not valid JSON",
+    );
+  });
+
+  it("should throw error for version 1 payload", async () => {
+    const v1Payload = {
+      version: 1,
+      data: {
+        someField: "value",
+      },
+    };
+    const v1PayloadString = JSON.stringify(v1Payload);
+    console.log("Payload string:", v1PayloadString); // Debug log
+    const signature = await generateSignature(timestamp, v1PayloadString);
+    const headers = {
+      "x-payload-signature": signature,
+      "x-timestamp": timestamp,
+    };
+
+    await expect(parse(v1PayloadString, headers, secret)).rejects.toThrow(
+      "Invalid webhook payload: version 1 is no longer supported, please upgrade to webhook version 2.",
+    );
+  });
+
+  it("should accept payload within tolerance window", async () => {
+    const recentTimestamp = (Math.floor(Date.now() / 1000) - 200).toString(); // 200 seconds old
+    const signature = await generateSignature(recentTimestamp, payloadString);
+    const headers = {
+      "x-payload-signature": signature,
+      "x-timestamp": recentTimestamp,
+    };
+
+    const result = await parse(payloadString, headers, secret, 300);
+    expect(result).toEqual(validPayload);
+  });
+});
diff --git a/packages/thirdweb/src/bridge/Webhook.ts b/packages/thirdweb/src/bridge/Webhook.ts
@@ -0,0 +1,119 @@
+/**
+ * Parses an incoming webhook from thirdweb.
+ *
+ * @param payload - The raw text body received from thirdweb.
+ * @param headers - The webhook headers received from thirdweb.
+ * @param secret - The webhook secret to verify the payload with.
+ */
+export async function parse<T extends Record<string, unknown>>(
+  /**
+   * Raw text body received from thirdweb.
+   */
+  payload: string,
+
+  /**
+   * The webhook headers received from thirdweb.
+   */
+  headers: Record<string, string>,
+
+  /**
+   * The webhook secret to verify the payload with.
+   */
+  secret: string,
+
+  /**
+   * The tolerance in seconds for the timestamp verification.
+   */
+  tolerance = 300, // Default to 5 minutes if not specified
+) {
+  // Get the signature and timestamp from headers
+  const receivedSignature =
+    headers["x-payload-signature"] || headers["x-pay-signature"];
+  const receivedTimestamp =
+    headers["x-timestamp"] || headers["x-pay-timestamp"];
+
+  if (!receivedSignature || !receivedTimestamp) {
+    throw new Error("Missing required webhook headers: signature or timestamp");
+  }
+
+  // Verify timestamp
+  const now = Math.floor(Date.now() / 1000);
+  const timestamp = Number.parseInt(receivedTimestamp, 10);
+  const diff = Math.abs(now - timestamp);
+
+  if (diff > tolerance) {
+    throw new Error(
+      `Webhook timestamp is too old. Difference: ${diff}s, tolerance: ${tolerance}s`,
+    );
+  }
+
+  // Generate signature using the same method as the sender
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(`${receivedTimestamp}.${payload}`),
+  );
+
+  // Convert the signature to hex string
+  const computedSignature = Array.from(new Uint8Array(signature))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+
+  // Compare signatures
+  if (computedSignature !== receivedSignature) {
+    throw new Error("Invalid webhook signature");
+  }
+
+  // Parse the payload as JSON
+  let parsedPayload: WebhookPayload<T>;
+  try {
+    parsedPayload = JSON.parse(payload) as WebhookPayload<T>;
+  } catch {
+    throw new Error("Invalid webhook payload: not valid JSON");
+  }
+
+  // Check version after successful JSON parsing
+  if (parsedPayload.version === 1) {
+    throw new Error(
+      "Invalid webhook payload: version 1 is no longer supported, please upgrade to webhook version 2.",
+    );
+  }
+
+  return parsedPayload;
+}
+
+export type WebhookPayload<T = Record<string, unknown>> =
+  | {
+      version: 1;
+      data: Record<string, unknown>;
+    }
+  | {
+      version: 2;
+      data: {
+        transactionId: string;
+        paymentId: string;
+        clientId: string;
+        action: string;
+        status: string;
+        originToken: string;
+        originAmount: string;
+        destinationToken: `0x${string}`;
+        destinationAmount: string;
+        sender: `0x${string}`;
+        receiver: `0x${string}`;
+        type: string;
+        transactions: string[];
+        developerFeeBps: number;
+        developerFeeRecipient: `0x${string}`;
+        purchaseData: T;
+      };
+    };
diff --git a/packages/thirdweb/src/bridge/index.ts b/packages/thirdweb/src/bridge/index.ts
@@ -2,9 +2,11 @@ export * as Buy from "./Buy.js";
 export * as Sell from "./Sell.js";
 export * as Transfer from "./Transfer.js";
 export * as Onramp from "./Onramp.js";
+export * as Webhook from "./Webhook.js";
 export { status } from "./Status.js";
 export { routes } from "./Routes.js";
 export { chains } from "./Chains.js";
+export { parse } from "./Webhook.js";
 
 export type { Chain } from "./types/Chain.js";
 export type { Quote, PreparedQuote } from "./types/Quote.js";
@@ -17,3 +19,4 @@ export type {
 export type { Status } from "./types/Status.js";
 export type { Token } from "./types/Token.js";
 export type { BridgeAction } from "./types/BridgeAction.js";
+export type { WebhookPayload } from "./Webhook.js";
