Add support for validating webhooks

Author: mattt

index.d.ts

@@ -82,6 +82,10 @@ declare module "replicate" {
     retry?: number;
   }
 
+  export interface WebhookSecret {
+    key: string;
+  }
+
   export default class Replicate {
     constructor(options?: {
       auth?: string;
@@ -222,5 +226,26 @@ declare module "replicate" {
       cancel(training_id: string): Promise<Training>;
       list(): Promise<Page<Training>>;
     };
+
+    webhooks: {
+      default: {
+        secret: {
+          get(): Promise<WebhookSecret>;
+        };
+      };
+    };
   }
+
+  export function validateWebhook(
+    requestData:
+      | Request
+      | {
+          id?: string;
+          timestamp?: string;
+          body: string;
+          secret?: string;
+          signature?: string;
+        },
+    secret: string
+  ): boolean;
 }

index.js

@@ -1,14 +1,15 @@
 const ApiError = require("./lib/error");
 const ModelVersionIdentifier = require("./lib/identifier");
 const { Stream } = require("./lib/stream");
-const { withAutomaticRetries } = require("./lib/util");
+const { withAutomaticRetries, validateWebhook } = require("./lib/util");
 
 const collections = require("./lib/collections");
 const deployments = require("./lib/deployments");
 const hardware = require("./lib/hardware");
 const models = require("./lib/models");
 const predictions = require("./lib/predictions");
 const trainings = require("./lib/trainings");
+const webhooks = require("./lib/webhooks");
 
 const packageJSON = require("./package.json");
 
@@ -85,6 +86,14 @@ class Replicate {
       cancel: trainings.cancel.bind(this),
       list: trainings.list.bind(this),
     };
+
+    this.webhooks = {
+      default: {
+        secret: {
+          get: webhooks.default.secret.get.bind(this),
+        },
+      },
+    };
   }
 
   /**
@@ -359,3 +368,4 @@ class Replicate {
 }
 
 module.exports = Replicate;
+module.exports.validateWebhook = validateWebhook;

index.test.ts

@@ -1,5 +1,10 @@
 import { expect, jest, test } from "@jest/globals";
-import Replicate, { ApiError, Model, Prediction } from "replicate";
+import Replicate, {
+  ApiError,
+  Model,
+  Prediction,
+  validateWebhook,
+} from "replicate";
 import nock from "nock";
 import fetch from "cross-fetch";
 
@@ -980,5 +985,37 @@ describe("Replicate client", () => {
     });
   });
 
+  describe("webhooks.default.secret.get", () => {
+    test("Calls the correct API route", async () => {
+      nock(BASE_URL).get("/webhooks/default/secret").reply(200, {
+        key: "whsec_5WbX5kEWLlfzsGNjH64I8lOOqUB6e8FH",
+      });
+
+      const secret = await client.webhooks.default.secret.get();
+      expect(secret.key).toBe("whsec_5WbX5kEWLlfzsGNjH64I8lOOqUB6e8FH");
+    });
+
+    test("Can be used to validate webhook", () => {
+      const secret = "whsec_5WbX5kEWLlfzsGNjH64I8lOOqUB6e8FH";
+
+      const request = new Request("http://test.host/webhook", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Webhook-ID": "123",
+          "Webhook-Timestamp": "1707329251",
+          "Webhook-Signature":
+            "v1,3Bh4jH4/KdieFo0oCZw+piC59XQiH4s1ySUQz+FgJqI=",
+        },
+        body: JSON.stringify({ event: "output", data: "Hello, world!" }),
+      });
+
+      const isValid = validateWebhook(request, secret);
+      expect(isValid).toBe(true);
+    });
+
+    // Add more tests for error handling, edge cases, etc.
+  });
+
   // Continue with tests for other methods
 });

lib/util.js

@@ -1,5 +1,77 @@
+const crypto = require("node:crypto");
+
 const ApiError = require("./error");
 
+/**
+ * @see {@link validateWebhook}
+ * @overload
+ * @param {object} requestData - The request data
+ * @param {string} requestData.id - The webhook ID header from the incoming request.
+ * @param {string} requestData.timestamp - The webhook timestamp header from the incoming request.
+ * @param {string} requestData.body - The raw body of the incoming webhook request.
+ * @param {string} requestData.secret - The webhook secret, obtained from `replicate.webhooks.defaul.secret` method.
+ * @param {string} requestData.signature - The webhook signature header from the incoming request, comprising one or more space-delimited signatures.
+ */
+
+/**
+ * @see {@link validateWebhook}
+ * @overload
+ * @param {object} requestData - The request object
+ * @param {object} requestData.headers - The request headers
+ * @param {string} requestData.headers["webhook-id"] - The webhook ID header from the incoming request
+ * @param {string} requestData.headers["webhook-timestamp"] - The webhook timestamp header from the incoming request
+ * @param {string} requestData.headers["webhook-signature"] - The webhook signature header from the incoming request, comprising one or more space-delimited signatures
+ * @param {string} requestData.body - The raw body of the incoming webhook request
+ * @param {string} secret - The webhook secret, obtained from `replicate.webhooks.defaul.secret` method
+ */
+
+/**
+ * Validate a webhook signature
+ *
+ * @returns {boolean} - True if the signature is valid
+ * @throws {Error} - If the request is missing required headers, body, or secret
+ */
+function validateWebhook(requestData, secret) {
+  let { id, timestamp, body, signature } = requestData;
+  const signingSecret = secret || requestData.secret;
+
+  if (requestData && requestData.headers && requestData.body) {
+    id = requestData.headers.get("webhook-id");
+    timestamp = requestData.headers.get("webhook-timestamp");
+    signature = requestData.headers.get("webhook-signature");
+    body = requestData.body;
+  }
+
+  if (!id || !timestamp || !signature) {
+    throw new Error("Missing required webhook headers");
+  }
+
+  if (!body) {
+    throw new Error("Missing required body");
+  }
+
+  if (!signingSecret) {
+    throw new Error("Missing required secret");
+  }
+
+  const signedContent = `${id}.${timestamp}.${body}`;
+
+  const secretBytes = Buffer.from(signingSecret.split("_")[1], "base64");
+
+  const computedSignature = crypto
+    .createHmac("sha256", secretBytes)
+    .update(signedContent)
+    .digest("base64");
+
+  const expectedSignatures = signature
+    .split(" ")
+    .map((sig) => sig.split(",")[1]);
+
+  return expectedSignatures.some(
+    (expectedSignature) => expectedSignature === computedSignature
+  );
+}
+
 /**
  * Automatically retry a request if it fails with an appropriate status code.
  *
@@ -68,4 +140,4 @@ async function withAutomaticRetries(request, options = {}) {
   return request();
 }
 
-module.exports = { withAutomaticRetries };
+module.exports = { validateWebhook, withAutomaticRetries };

lib/webhooks.js

@@ -0,0 +1,20 @@
+/**
+ * Get the default webhook signing secret
+ *
+ * @returns {Promise<object>} Resolves with the signing secret for the default webhook
+ */
+async function getDefaultWebhookSecret() {
+  const response = await this.request("/webhooks/default/secret", {
+    method: "GET",
+  });
+
+  return response.json();
+}
+
+module.exports = {
+  default: {
+    secret: {
+      get: getDefaultWebhookSecret,
+    },
+  },
+};