Merge pull request #59 from rishavbhowmik/dev-webhook-signature

Webhook signature verification tool

Author: imagekitio

README.md

@@ -1125,6 +1125,105 @@ 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.
+
+Verifing webhook signature is easy with imagekit SDK. All you need is `x-ik-signature`, rawRequestBody and secretKey. You can copy webhook secret from imagekit dashboard.
+
+```js
+try {
+    const {
+        timestamp,  // Unix timestamp in milliseconds
+        event,      // Parsed webhook event object
+    } = imagekit.verifyWebhookEvent(
+        '{"type":"video.transformation.accepted","id":"58e6d24d-6098-4319-be8d-40c3cb0a402d"...', // Raw request body encoded as Uint8Array or UTF8 string
+        't=1655788406333,v1=d30758f47fcb31e1fa0109d3b3e2a6c623e699aaf1461cba6bd462ef58ea4b31', // Request header `x-ik-signature`
+        'whsec_...' // Webhook secret
+    )
+    // { timestamp: 1655788406333, event: {"type":"video.transformation.accepted","id":"58e6d24d-6098-4319-be8d-40c3cb0a402d"...} }
+} catch (err) {
+    // `verifyWebhookEvent` will throw an error if the signature is invalid
+    // And the webhook event must be ignored and not processed
+    console.log(err);
+    // Under normal circumstances you may catch following errors:
+    // - `Error: Incorrect signature` - you may check the webhook secret & the request body being used.
+    // - `Error: Signature missing` or `Error: Timestamp missing` or `Error: Invalid timestamp` - you may check `x-ik-signature` header used.
+}
+```
+
+Here is an example for implementing with express.js server.
+
+```js
+const express = require('express');
+const Imagekit = require('imagekit');
+
+// Webhook configs
+const WEBHOOK_ENDPOINT = '/webhook';
+const WEBHOOK_SECRET = 'whsec_...'; // Copy from Imagekit dashboard
+const WEBHOOK_EXPIRY_DURATION = 60 * 1000; // 60 seconds
+
+// Server configs
+const PORT = 8081;
+
+const imagekit = new Imagekit({
+  publicKey: 'pub_...',
+  urlEndpoint: 'https://ik.imagekit.io/example',
+  privateKey: 'pvt_...',
+})
+
+const app = express();
+
+app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  // Get `x-ik-signature` from webhook request header & rawRequestBody
+  const signature = req.headers["x-ik-signature"]; // eg. 't=1655788406333,v1=d30758f47fcb31e1fa0109d3b3e2a6c623e699aaf1461cba6bd462ef58ea4b31'
+  const rawBody = req.rawBody;// Unmodified request body encoded as Uint8Array or UTF8 string
+
+  // Verify signature & parse event
+  let webhookResult;
+  try {
+    webhookResult = imagekit.verifyWebhookEvent(rawBody, signature, WEBHOOK_SECRET);
+    // `verifyWebhookEvent` method will throw an error if signature is invalid
+  } catch (e) {
+    // Failed to verify webhook
+    return res.status(401).send(`Webhook error: ${e.message}`);
+  }
+  const { timestamp, event } = webhookResult;
+
+  // Check if webhook has expired
+  if (timestamp + WEBHOOK_EXPIRY_DURATION < Date.now()) {
+    return res.status(401).send('Webhook signature expired');
+  }
+
+  // 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;
+    // ... handle other event types
+    default:
+      console.log(`Unhandled event type ${event.type}`);
+  }
+
+  // Acknowledge webhook is received and processed successfully
+  res.status(200).end();
+});
+
+app.listen(PORT, () => {
+  console.log(`Server listening on port ${PORT}`);
+  console.log(
+    `Webhook endpoint: 'http://localhost:${PORT}${WEBHOOK_ENDPOINT}'`,
+    'Do replace 'localhost' with public endpoint'
+  );
+});
+```
+
 ## 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 \{ `timstamp`: 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,80 @@
+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;

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",