Merge pull request #60 from imagekit-developer/dev

Webhook signature

Author: imagekitio

README.md

@@ -1125,6 +1125,76 @@ When you exceed the rate limits for an endpoint, you will receive a `429` status
 | `X-RateLimit-Reset` | The amount of time in milliseconds before you can make another request to this endpoint. Pause/sleep your workflow for this duration. |
 | `X-RateLimit-Interval` | The duration of interval in milliseconds for which this rate limit was exceeded. |
 
+## Verify webhook events
+
+ImageKit sends `x-ik-signature` in the webhook request header, which can be used to verify the authenticity of the webhook request.
+
+Verifying webhook signature is easy with imagekit SDK. All you need is the value of the `x-ik-signature` header, request body, and [webhook secret](https://imagekit.io/dashboard/developer/webhooks) from the ImageKit dashboard.
+
+Here is an example using the express.js server.
+
+```js
+const express = require('express');
+const Imagekit = require('imagekit');
+
+// Webhook configs
+const WEBHOOK_SECRET = 'whsec_...'; // Copy from Imagekit dashboard
+const WEBHOOK_EXPIRY_DURATION = 300 * 1000; // 300 seconds for example
+
+const imagekit = new Imagekit({
+  publicKey: 'public_...',
+  urlEndpoint: 'https://ik.imagekit.io/imagekit_id',
+  privateKey: 'private_...',
+})
+
+const app = express();
+
+app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+    const signature = req.headers["x-ik-signature"];
+    const requestBody = req.body;
+    let webhookResult;
+    try {
+        webhookResult = imagekit.verifyWebhookEvent(requestBody, signature, WEBHOOK_SECRET);
+    } catch (e) {
+        // `verifyWebhookEvent` method will throw an error if signature is invalid
+        console.log(e);
+        // Return a response to acknowledge receipt of the event so that ImageKit doesn't retry sending this webhook.
+        res.send()
+    }
+
+    const { timestamp, event } = webhookResult;
+
+    // Check if webhook has expired
+    if (timestamp + WEBHOOK_EXPIRY_DURATION < Date.now()) {
+        // Return a response to acknowledge receipt of the event so that ImageKit doesn't retry sending this webhook.
+        res.send()
+    }
+
+    // Handle webhook
+    switch (event.type) {
+        case 'video.transformation.accepted':
+            // It is triggered when a new video transformation request is accepted for processing. You can use this for debugging purposes.
+            break;
+        case 'video.transformation.ready':
+            // It is triggered when a video encoding is finished, and the transformed resource is ready to be served. You should listen to this webhook and update any flag in your database or CMS against that particular asset so your application can start showing it to users.
+            break;
+        case 'video.transformation.error':
+            // It is triggered if an error occurs during encoding. Listen to this webhook to log the reason. You should check your origin and URL-endpoint settings if the reason is related to download failure. If the reason seems like an error on the ImageKit side, then raise a support ticket at [email protected].
+            break;
+        default:
+            // ... handle other event types
+            console.log(`Unhandled event type ${event.type}`);
+    }
+
+    // Return a response to acknowledge receipt of the event
+    res.send();
+})
+
+app.listen(3000, () => {
+    console.log(`Example app listening on port 3000`)
+})
+```
+
 ## Support
 
 For any feedback or to report any issues or general implementation support, please reach out to [[email protected]](mailto:[email protected])

index.ts

@@ -40,6 +40,7 @@ import { IKCallback } from "./libs/interfaces/IKCallback";
 import manage from "./libs/manage";
 import signature from "./libs/signature";
 import upload from "./libs/upload";
+import { verify as verifyWebhookEvent } from "./utils/webhook-signature";
 import customMetadataField from "./libs/manage/custom-metadata-field";
 /*
     Implementations
@@ -75,7 +76,6 @@ const promisify = function <T = void>(thisContext: ImageKit, fn: Function) {
     }
   };
 };
-
 class ImageKit {
   options: ImageKitOptions = {
     uploadEndpoint: "https://upload.imagekit.io/api/v1/files/upload",
@@ -667,6 +667,14 @@ class ImageKit {
   pHashDistance(firstPHash: string, secondPHash: string): number | Error {
     return pHashUtils.pHashDistance(firstPHash, secondPHash);
   }
+
+  /**
+   * @param payload - Raw webhook request body (Encoded as UTF8 string or Buffer)
+   * @param signature - Webhook signature as UTF8 encoded strings (Stored in `x-ik-signature` header of the request)
+   * @param secret - Webhook secret as UTF8 encoded string [Copy from ImageKit dashboard](https://imagekit.io/dashboard/developer/webhooks)
+   * @returns \{ `timestamp`: Verified UNIX epoch timestamp if signature, `event`: Parsed webhook event payload \}
+   */
+  verifyWebhookEvent = verifyWebhookEvent;
 }
 
-export = ImageKit;
+export = ImageKit;

libs/constants/errorMessages.ts

@@ -42,4 +42,9 @@ export default {
     "INVALID_FILE_PATH": { message: "Invalid value for filePath", help: "Pass the full path of the file. For example - /path/to/file.jpg" },
     "INVALID_NEW_FILE_NAME": { message: "Invalid value for newFileName. It should be a string.", help: "" },
     "INVALID_PURGE_CACHE": { message: "Invalid value for purgeCache. It should be boolean.", help: "" },
+    // Webhook signature
+    "VERIFY_WEBHOOK_EVENT_SIGNATURE_INCORRECT": { message: "Incorrect signature", help: "Please pass x-ik-signature header as utf8 string" },
+    "VERIFY_WEBHOOK_EVENT_SIGNATURE_MISSING": { message: "Signature missing", help: "Please pass x-ik-signature header as utf8 string" },
+    "VERIFY_WEBHOOK_EVENT_TIMESTAMP_MISSING": { message: "Timestamp missing", help: "Please pass x-ik-signature header as utf8 string" },
+    "VERIFY_WEBHOOK_EVENT_TIMESTAMP_INVALID": { message: "Timestamp invalid", help: "Please pass x-ik-signature header as utf8 string" },
 };

libs/interfaces/index.ts

@@ -17,6 +17,12 @@ import { MoveFolderOptions, MoveFolderResponse, MoveFolderError } from "./MoveFo
 import { DeleteFileVersionOptions, RestoreFileVersionOptions } from "./FileVersion"
 import { CreateCustomMetadataFieldOptions, CustomMetadataField, UpdateCustomMetadataFieldOptions, GetCustomMetadataFieldsOptions } from "./CustomMetatadaField"
 import { RenameFileOptions, RenameFileResponse } from "./Rename"
+import {
+  WebhookEvent,
+  WebhookEventVideoTransformationAccepted,
+  WebhookEventVideoTransformationReady,
+  WebhookEventVideoTransformationError,
+} from "./webhookEvent";
 
 type FinalUrlOptions = ImageKitOptions & UrlOptions; // actual options used to construct url
 
@@ -56,5 +62,9 @@ export type {
   UpdateCustomMetadataFieldOptions,
   RenameFileOptions,
   RenameFileResponse,
+  WebhookEvent,
+  WebhookEventVideoTransformationAccepted,
+  WebhookEventVideoTransformationReady,
+  WebhookEventVideoTransformationError,
 };
 export type { IKCallback } from "./IKCallback";

libs/interfaces/webhookEvent.ts

@@ -0,0 +1,81 @@
+type Asset = {
+  url: string;
+};
+
+type TransformationOptions = {
+  video_codec: string;
+  audio_codec: string;
+  auto_rotate: boolean;
+  quality: number;
+  format: string;
+};
+
+interface WebhookEventBase {
+  type: string;
+  id: string;
+  created_at: string; // Date
+}
+
+/** WebhookEvent for "video.transformation.*" type */
+interface WebhookEventVideoTransformationBase extends WebhookEventBase {
+  request: {
+    x_request_id: string;
+    url: string;
+    user_agent: string;
+  };
+}
+
+export interface WebhookEventVideoTransformationAccepted extends WebhookEventVideoTransformationBase {
+  type: "video.transformation.accepted";
+  data: {
+    asset: Asset;
+    transformation: {
+      type: string;
+      options: TransformationOptions;
+    };
+  };
+}
+
+export interface WebhookEventVideoTransformationReady extends WebhookEventVideoTransformationBase {
+  type: "video.transformation.ready";
+  timings: {
+    donwload_duration: number;
+    encoding_duration: number;
+  };
+  data: {
+    asset: Asset;
+    transformation: {
+      type: string;
+      options: TransformationOptions;
+      output: {
+        url: string;
+        video_metadata: {
+          duration: number;
+          width: number;
+          height: number;
+          bitrate: number;
+        };
+      };
+    };
+  };
+}
+
+export interface WebhookEventVideoTransformationError extends WebhookEventVideoTransformationBase {
+  type: "video.transformation.error";
+  data: {
+    asset: Asset;
+    transformation: {
+      type: string;
+      options: TransformationOptions;
+      error: {
+        reason: string;
+      };
+    };
+  };
+}
+
+export type WebhookEvent =
+  | WebhookEventVideoTransformationAccepted
+  | WebhookEventVideoTransformationReady
+  | WebhookEventVideoTransformationError
+  | Object;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "imagekit",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "Offical NodeJS SDK for ImageKit.io integration",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

tests/webhook-signature.js

@@ -0,0 +1,145 @@
+import ImageKit from "../index";
+import { expect } from "chai";
+
+// Sample webhook data
+const WEBHOOK_REQUEST_SAMPLE_SECRET = "whsec_xeO2UNkfKMQnfJf7Q/Qx+fYptL1wabXd";
+const WEBHOOK_REQUEST_SAMPLE_TIMESTAMP = new Date(1655788406333);
+const WEBHOOK_REQUEST_SAMPLE_SIGNATURE_HEADER =
+  "t=1655788406333,v1=d30758f47fcb31e1fa0109d3b3e2a6c623e699aaf1461cba6bd462ef58ea4b31";
+const WEBHOOK_REQUEST_SAMPLE_RAW_BODY =
+  '{"type":"video.transformation.accepted","id":"58e6d24d-6098-4319-be8d-40c3cb0a402d","created_at":"2022-06-20T11:59:58.461Z","request":{"x_request_id":"fa98fa2e-d6cd-45b4-acf5-bc1d2bbb8ba9","url":"http://ik.imagekit.io/demo/sample-video.mp4?tr=f-webm,q-10","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:101.0) Gecko/20100101 Firefox/101.0"},"data":{"asset":{"url":"http://ik.imagekit.io/demo/sample-video.mp4"},"transformation":{"type":"video-transformation","options":{"video_codec":"vp9","audio_codec":"opus","auto_rotate":true,"quality":10,"format":"webm"}}}}';
+const WEBHOOK_REQUEST_SAMPLE = Object.seal({
+  secret: WEBHOOK_REQUEST_SAMPLE_SECRET,
+  timestamp: WEBHOOK_REQUEST_SAMPLE_TIMESTAMP,
+  signatureHeader: WEBHOOK_REQUEST_SAMPLE_SIGNATURE_HEADER,
+  rawBody: WEBHOOK_REQUEST_SAMPLE_RAW_BODY,
+  body: JSON.parse(WEBHOOK_REQUEST_SAMPLE_RAW_BODY),
+});
+
+describe("WebhookSignature", function () {
+  const verify = (new ImageKit(require("./data").initializationParams)).verifyWebhookEvent;
+
+  context("Test Webhook.verify() - Positive cases", () => {
+    it("Verify with body as string", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const { timestamp, event } = verify(
+        webhookRequest.rawBody,
+        webhookRequest.signatureHeader,
+        webhookRequest.secret
+      );
+      expect(timestamp).to.equal(webhookRequest.timestamp.getTime());
+      expect(event).to.deep.equal(webhookRequest.body);
+    });
+    it("Verify with body as Buffer", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const { timestamp, event } = verify(
+        Buffer.from(webhookRequest.rawBody),
+        webhookRequest.signatureHeader,
+        webhookRequest.secret
+      );
+      expect(timestamp).to.equal(webhookRequest.timestamp.getTime());
+      expect(event).to.deep.equal(webhookRequest.body);
+    });
+    it("Verify with body as Uint8Array", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const rawBody = Uint8Array.from(Buffer.from(webhookRequest.rawBody));
+      const { timestamp, event } = verify(
+        rawBody,
+        webhookRequest.signatureHeader,
+        webhookRequest.secret
+      );
+      expect(timestamp).to.equal(webhookRequest.timestamp.getTime());
+      expect(event).to.deep.equal(webhookRequest.body);
+    });
+  });
+
+  context("Test WebhookSignature.verify() - Negative cases", () => {
+    it("Timestamp missing", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const invalidSignature =
+        "v1=b6bc2aa82491c32f1cbef0eb52b7ffffff467ea65a03b5d4ccdcfb9e0941c946";
+      try {
+        verify(webhookRequest.rawBody, invalidSignature, webhookRequest.secret);
+        expect.fail("Expected exception");
+      } catch (e) {
+        expect(e.message).to.equal("Timestamp missing");
+      }
+    });
+    it("Timestamp invalid", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const invalidSignature =
+        "t=notANumber,v1=b6bc2aa82491c32f1cbef0eb52b7ffffff467ea65a03b5d4ccdcfb9e0941c946";
+      try {
+        verify(webhookRequest.rawBody, invalidSignature, webhookRequest.secret);
+        expect.fail("Expected exception");
+      } catch (e) {
+        expect(e.message).to.equal("Timestamp invalid");
+      }
+    });
+    it("Signature missing", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const invalidSignature = "t=1656326161409";
+      try {
+        verify(webhookRequest.rawBody, invalidSignature, webhookRequest.secret);
+        expect.fail("Expected exception");
+      } catch (e) {
+        expect(e.message).to.equal("Signature missing");
+      }
+    });
+    it("Incorrect signature - v1 manipulated", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const invalidSignature = `t=${webhookRequest.timestamp.getTime()},v1=d66b01d8f1e158d1af7646184716037510ac8ce0a1e70b726a1b698f954785b2`;
+      try {
+        verify(webhookRequest.rawBody, invalidSignature, webhookRequest.secret);
+        expect.fail("Expected exception");
+      } catch (e) {
+        expect(e.message).to.equal("Incorrect signature");
+      }
+    });
+    it("Incorrect signature - incorrect request body", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const incorrectBody = { hello: "world" };
+      const incorrectRawBody = JSON.stringify(incorrectBody);
+      try {
+        verify(
+          incorrectRawBody,
+          webhookRequest.signatureHeader,
+          webhookRequest.secret
+        );
+        expect.fail("Expected exception");
+      } catch (e) {
+        expect(e.message).to.equal("Incorrect signature");
+      }
+    });
+    it("Incorrect signature - timestamp manipulated", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      const incorrectSignature = webhookRequest.signatureHeader.replace(
+        `t=${webhookRequest.timestamp.getTime()}`,
+        `t=${webhookRequest.timestamp.getTime() + 1}`
+      ); // Correct timestamp replaced with incorrect timestamp
+      try {
+        verify(
+          webhookRequest.rawBody,
+          incorrectSignature,
+          webhookRequest.secret
+        );
+        expect.fail("Expected exception");
+      } catch (e) {
+        expect(e.message).to.equal("Incorrect signature");
+      }
+    });
+    it("Incorrect signature - different secret", () => {
+      const webhookRequest = WEBHOOK_REQUEST_SAMPLE;
+      try {
+        verify(
+          webhookRequest.rawBody,
+          webhookRequest.signatureHeader,
+          "A different secret"
+        );
+        expect.fail("Expected exception");
+      } catch (e) {
+        expect(e.message).to.equal("Incorrect signature");
+      }
+    });
+  });
+});