Add webhook verification functionality for secure payload validation

Author: jnsdls

.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
+);
+``` 

packages/thirdweb/src/bridge/Webhook.test.ts

@@ -0,0 +1,338 @@
+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: "TRANSFER",
+      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);
+    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);
+  });
+
+  describe("payload validation", () => {
+    it("should throw error for non-object payload", async () => {
+      const invalidPayload = JSON.stringify("not-an-object");
+      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: must be an object",
+      );
+    });
+
+    it("should throw error for missing version", async () => {
+      const invalidPayload = {
+        data: {
+          transactionId: "tx123",
+        },
+      };
+      const payloadString = JSON.stringify(invalidPayload);
+      const signature = await generateSignature(timestamp, payloadString);
+      const headers = {
+        "x-payload-signature": signature,
+        "x-timestamp": timestamp,
+      };
+
+      await expect(parse(payloadString, headers, secret)).rejects.toThrow(
+        "Invalid webhook payload: version must be a number",
+      );
+    });
+
+    it("should throw error for missing data object", async () => {
+      const invalidPayload = {
+        version: 2,
+      };
+      const payloadString = JSON.stringify(invalidPayload);
+      const signature = await generateSignature(timestamp, payloadString);
+      const headers = {
+        "x-payload-signature": signature,
+        "x-timestamp": timestamp,
+      };
+
+      await expect(parse(payloadString, headers, secret)).rejects.toThrow(
+        "Invalid webhook payload: version 2 must have a data object",
+      );
+    });
+
+    it("should throw error for missing required fields", async () => {
+      const invalidPayload = {
+        version: 2,
+        data: {
+          transactionId: "tx123",
+          // Missing other required fields
+        },
+      };
+      const payloadString = JSON.stringify(invalidPayload);
+      const signature = await generateSignature(timestamp, payloadString);
+      const headers = {
+        "x-payload-signature": signature,
+        "x-timestamp": timestamp,
+      };
+
+      await expect(parse(payloadString, headers, secret)).rejects.toThrow(
+        "Invalid webhook payload: missing required field 'paymentId'",
+      );
+    });
+
+    it("should throw error for invalid action type", async () => {
+      const invalidPayload = {
+        version: 2,
+        data: {
+          ...validPayload.data,
+          action: "INVALID_ACTION", // Invalid action type
+        },
+      };
+      const payloadString = JSON.stringify(invalidPayload);
+      const signature = await generateSignature(timestamp, payloadString);
+      const headers = {
+        "x-payload-signature": signature,
+        "x-timestamp": timestamp,
+      };
+
+      await expect(parse(payloadString, headers, secret)).rejects.toThrow(
+        "Invalid webhook payload: action must be one of: TRANSFER, BUY, SELL",
+      );
+    });
+
+    it("should throw error for invalid status type", async () => {
+      const invalidPayload = {
+        version: 2,
+        data: {
+          ...validPayload.data,
+          status: "INVALID_STATUS", // Invalid status type
+        },
+      };
+      const payloadString = JSON.stringify(invalidPayload);
+      const signature = await generateSignature(timestamp, payloadString);
+      const headers = {
+        "x-payload-signature": signature,
+        "x-timestamp": timestamp,
+      };
+
+      await expect(parse(payloadString, headers, secret)).rejects.toThrow(
+        "Invalid webhook payload: status must be one of: PENDING, FAILED, COMPLETED",
+      );
+    });
+
+    it("should throw error for invalid hex address", async () => {
+      const invalidPayload = {
+        version: 2,
+        data: {
+          ...validPayload.data,
+          destinationToken: "invalid-address", // Invalid hex address
+        },
+      };
+      const payloadString = JSON.stringify(invalidPayload);
+      const signature = await generateSignature(timestamp, payloadString);
+      const headers = {
+        "x-payload-signature": signature,
+        "x-timestamp": timestamp,
+      };
+
+      await expect(parse(payloadString, headers, secret)).rejects.toThrow(
+        "Invalid webhook payload: destinationToken must be a valid hex address",
+      );
+    });
+
+    it("should throw error for invalid transactions array", async () => {
+      const invalidPayload = {
+        version: 2,
+        data: {
+          ...validPayload.data,
+          transactions: "not-an-array", // Invalid transactions type
+        },
+      };
+      const payloadString = JSON.stringify(invalidPayload);
+      const signature = await generateSignature(timestamp, payloadString);
+      const headers = {
+        "x-payload-signature": signature,
+        "x-timestamp": timestamp,
+      };
+
+      await expect(parse(payloadString, headers, secret)).rejects.toThrow(
+        "Invalid webhook payload: transactions must be an array",
+      );
+    });
+
+    it("should throw error for invalid developerFeeBps type", async () => {
+      const invalidPayload = {
+        version: 2,
+        data: {
+          ...validPayload.data,
+          developerFeeBps: "100", // Invalid type (string instead of number)
+        },
+      };
+      const payloadString = JSON.stringify(invalidPayload);
+      const signature = await generateSignature(timestamp, payloadString);
+      const headers = {
+        "x-payload-signature": signature,
+        "x-timestamp": timestamp,
+      };
+
+      await expect(parse(payloadString, headers, secret)).rejects.toThrow(
+        "Invalid webhook payload: developerFeeBps must be a number",
+      );
+    });
+
+    it("should throw error for invalid purchaseData type", async () => {
+      const invalidPayload = {
+        version: 2,
+        data: {
+          ...validPayload.data,
+          purchaseData: null, // Invalid purchaseData type
+        },
+      };
+      const payloadString = JSON.stringify(invalidPayload);
+      const signature = await generateSignature(timestamp, payloadString);
+      const headers = {
+        "x-payload-signature": signature,
+        "x-timestamp": timestamp,
+      };
+
+      await expect(parse(payloadString, headers, secret)).rejects.toThrow(
+        "Invalid webhook payload: purchaseData must be an object",
+      );
+    });
+  });
+});