Webhooks for when renderMediaOnLambda() is finished

packages/docs/docs/lambda/rendermediaonlambda.md

@@ -223,7 +223,7 @@ The S3 bucket name in which all files are being saved.
 
 ### `cloudWatchLogs`
 
-_Available from v3.2.10_
+_available from v3.2.10_
 
 A link to CloudWatch (if you haven't disabled it) that you can visit to see the logs for the render.
 
@@ -235,6 +235,16 @@ If a custom out name is specified and a file already exists at this key in the S
 
 An existing file at the output S3 key will conflict with the render and must be deleted beforehand. If this setting is `false` and a conflict occurs, an error will be thrown.
 
+### `webhook`
+
+_optional, available from v3.2.XX_
+
+If specified, Remotion will send a POST request to the provided endpoint to notify your application when the Lambda rendering process finishes, errors out or times out.
+
+The request headers include a cryptographic signature that you can use to [validate incoming webhooks](/docs/lambda/validate-webhooks).
+
+DOCUMENT RESPONSE
+
 ## See also
 
 - [Source code for this function](https://github.com/remotion-dev/remotion/blob/main/packages/lambda/src/api/render-media-on-lambda.ts)

packages/docs/docs/lambda/validate-webhooks.md

@@ -0,0 +1,25 @@
+---
+sidebar_label: Validate Webhooks
+title: Validate Webhooks
+slug: /lambda/validate-webhooks
+---
+
+```javascript
+import * as Crypto from "crypto";
+
+// Express API endpoint
+router.post("/my-remotion-webhook-endpoint", (req, res) => {
+  const hmac = Crypto.createHmac("sha1", REMOTION_AWS_SECRET_ACCESS_KEY);
+  const signature = `sha1=${hmac
+    .update(JSON.stringify(req.body))
+    .digest("hex")}`;
+
+  if (signature !== req.header("X-Remotion-Signature")) {
+    // Request wasn't sent by Remotion
+    // ...
+  } else {
+    // Request was sent by Remotion
+    // ...
+  }
+});
+```

packages/docs/sidebars.js

@@ -314,6 +314,7 @@ module.exports = {
         "lambda/custom-layers",
         "lambda/custom-destination",
         "lambda/checklist",
+        "lambda/validate-webhooks",
         {
           type: "category",
           label: "Troubleshooting",

packages/lambda/src/api/render-media-on-lambda.ts

@@ -48,6 +48,7 @@ export type RenderMediaOnLambdaInput = {
 	downloadBehavior?: DownloadBehavior | null;
 	muted?: boolean;
 	overwrite?: boolean;
+	webhook?: string
 };
 
 export type RenderMediaOnLambdaOutput = {
@@ -72,6 +73,7 @@ export type RenderMediaOnLambdaOutput = {
  * @param params.region The AWS region in which the media should be rendered.
  * @param params.maxRetries How often rendering a chunk may fail before the media render gets aborted. Default "1"
  * @param params.logLevel Level of logging that Lambda function should perform. Default "info".
+ * @param params.webhook Webhook URL to be called upon completion or timeout of the rendering process.
  * @returns {Promise<RenderMediaOnLambdaOutput>} See documentation for detailed structure
  */
 
@@ -103,6 +105,7 @@ export const renderMediaOnLambda = async ({
 	downloadBehavior,
 	muted,
 	overwrite,
+	webhook,
 }: RenderMediaOnLambdaInput): Promise<RenderMediaOnLambdaOutput> => {
 	const actualCodec = validateLambdaCodec(codec);
 	validateServeUrl(serveUrl);
@@ -143,6 +146,7 @@ export const renderMediaOnLambda = async ({
 				muted: muted ?? false,
 				version: VERSION,
 				overwrite: overwrite ?? false,
+				webhook,
 			},
 			region,
 		});

packages/lambda/src/cli/args.ts

@@ -27,6 +27,7 @@ type LambdaCommandLineOptions = {
 	['architecture']: LambdaArchitecture;
 	['custom-role-arn']: string | undefined;
 	privacy: Privacy;
+	webhook: string | undefined;
 };
 
 export const parsedLambdaCli = minimist<LambdaCommandLineOptions>(

packages/lambda/src/cli/commands/render/render.ts

@@ -111,6 +111,7 @@ export const renderCommand = async (args: string[]) => {
 		concurrencyPerLambda: parsedLambdaCli['concurrency-per-lambda'],
 		muted,
 		overwrite,
+		webhook: parsedLambdaCli.webhook ?? undefined
 	});
 
 	const totalSteps = outName ? 5 : 4;

packages/lambda/src/functions/launch.ts

@@ -18,6 +18,7 @@ import {
 	rendersPrefix,
 } from '../shared/constants';
 import {DOCS_URL} from '../shared/docs-url';
+import {invokeWebhook} from '../shared/invoke-webhook';
 import {getServeUrlHash} from '../shared/make-s3-url';
 import {validateFramesPerLambda} from '../shared/validate-frames-per-lambda';
 import {validateOutname} from '../shared/validate-outname';
@@ -93,6 +94,27 @@ const innerLaunchHandler = async (params: LambdaPayload, options: Options) => {
 
 	const startedDate = Date.now();
 
+	let webhookInvoked = false;
+	const webhookDueToTimeout = setTimeout(async () => {
+		if (params.webhook && !webhookInvoked) {
+			try {
+				await invokeWebhook({
+					url: params.webhook,
+					type: 'timeout',
+					renderId: params.renderId,
+				});
+				webhookInvoked = true;
+			} catch (err) {
+				if (process.env.NODE_ENV === 'test') {
+					throw err;
+				}
+
+				console.log('Failed to invoke webhook:');
+				console.log(err);
+			}
+		}
+	}, Math.max(params.timeoutInMilliseconds - 1000, 1000));
+
 	const [browserInstance, optimization] = await Promise.all([
 		getBrowserInstance(
 			RenderInternals.isEqualOrBelowLogLevel(params.logLevel, 'verbose'),
@@ -515,6 +537,25 @@ const innerLaunchHandler = async (params: LambdaPayload, options: Options) => {
 	});
 
 	await Promise.all([cleanupChunksProm, fs.promises.rm(outfile)]);
+
+	clearTimeout(webhookDueToTimeout);
+	if (params.webhook && !webhookInvoked) {
+		try {
+			await invokeWebhook({
+				url: params.webhook,
+				type: 'success',
+				renderId: params.renderId,
+			});
+			webhookInvoked = true;
+		} catch (err) {
+			if (process.env.NODE_ENV === 'test') {
+				throw err;
+			}
+
+			console.log('Failed to invoke webhook:');
+			console.log(err);
+		}
+	}
 };
 
 export const launchHandler = async (
@@ -551,5 +592,21 @@ export const launchHandler = async (
 			expectedBucketOwner: options.expectedBucketOwner,
 			renderId: params.renderId,
 		});
+		if (params.webhook) {
+			try {
+				await invokeWebhook({
+					url: params.webhook,
+					type: 'error',
+					renderId: params.renderId,
+				});
+			} catch (error) {
+				if (process.env.NODE_ENV === 'test') {
+					throw error;
+				}
+
+				console.log('Failed to invoke webhook:');
+				console.log(error);
+			}
+		}
 	}
 };

packages/lambda/src/functions/start.ts

@@ -75,6 +75,7 @@ export const startHandler = async (params: LambdaPayload, options: Options) => {
 		downloadBehavior: params.downloadBehavior,
 		muted: params.muted,
 		overwrite: params.overwrite,
+		webhook: params.webhook,
 	};
 	await getLambdaClient(getCurrentRegionInFunction()).send(
 		new InvokeCommand({

packages/lambda/src/shared/constants.ts

@@ -226,6 +226,7 @@ export type LambdaPayloads = {
 		muted: boolean;
 		version: string;
 		overwrite: boolean;
+		webhook: string | undefined;
 	};
 	launch: {
 		type: LambdaRoutines.launch;
@@ -256,6 +257,7 @@ export type LambdaPayloads = {
 		downloadBehavior: DownloadBehavior;
 		muted: boolean;
 		overwrite: boolean;
+		webhook: string | undefined;
 	};
 	status: {
 		type: LambdaRoutines.status;

packages/lambda/src/shared/invoke-webhook.ts

@@ -0,0 +1,82 @@
+import * as Crypto from 'crypto';
+import http from 'http';
+import https from 'https';
+
+/**
+ * @description Calculates cryptographically secure signature for webhooks using Hmac.
+ * @link https://remotion.dev/docs/lambda/validate-webhooks
+ * @param payload Stringified request body to encode in the signature.
+ */
+export function calculateSignature(payload: string) {
+	const secret = 'INSECURE_DEFAULT_SECRET';
+	const hmac = Crypto.createHmac('sha1', secret);
+	const signature = 'sha1=' + hmac.update(payload).digest('hex');
+	return signature;
+}
+
+export type InvokeWebhookInput = {
+	url: string;
+	type: 'success' | 'error' | 'timeout';
+	renderId: string;
+};
+
+const getWebhookClient = (url: string) => {
+	if (url.startsWith('https://')) {
+		return mockableHttpClients.https;
+	}
+
+	if (url.startsWith('http://')) {
+		return mockableHttpClients.http;
+	}
+
+	throw new Error('Can only request URLs starting with http:// or https://');
+};
+
+export const mockableHttpClients = {
+	http: http.request,
+	https: https.request,
+};
+
+/**
+ * @description Calls a webhook.
+ * @link https://remotion.dev/docs/lambda/rendermediaonlambda#webhook
+ * @param params.url URL of webhook to call.
+ */
+export function invokeWebhook({url, type, renderId}: InvokeWebhookInput) {
+	const payload = JSON.stringify({result: type, renderId});
+
+	return new Promise<void>((resolve, reject) => {
+		const req = getWebhookClient(url)(
+			url,
+			{
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/json',
+					'X-Remotion-Signature': calculateSignature(payload),
+					'X-Remotion-Status': type,
+				},
+				timeout: 5000,
+			},
+			(res) => {
+				if (res.statusCode && res.statusCode > 299) {
+					reject(
+						new Error(
+							`Sent a webhook but got a status code of ${res.statusCode}`
+						)
+					);
+					return;
+				}
+
+				resolve();
+			}
+		);
+
+		req.write(payload);
+
+		req.on('error', (err) => {
+			reject(err);
+		});
+
+		req.end();
+	});
+}

packages/lambda/src/test/integration/renders/gif.test.ts

@@ -59,6 +59,7 @@ test('Should make a distributed GIF', async () => {
 			muted: false,
 			version: VERSION,
 			overwrite: true,
+			webhook: undefined,
 		},
 		extraContext
 	);

packages/lambda/src/test/integration/renders/old-version.test.ts

@@ -56,6 +56,7 @@ test('Should fail when using an incompatible version', async () => {
 				muted: false,
 				version: VERSION,
 				overwrite: true,
+				webhook: undefined,
 			},
 			extraContext
 		)

packages/lambda/src/test/integration/renders/other-bucket.test.ts

@@ -62,6 +62,7 @@ test('Should be able to render to another bucket', async () => {
 			muted: false,
 			version: VERSION,
 			overwrite: true,
+			webhook: undefined,
 		},
 		extraContext
 	);

packages/lambda/src/test/integration/renders/silent-audio.test.ts

@@ -59,6 +59,7 @@ test('Should add silent audio if there is no audio', async () => {
 			muted: false,
 			version: VERSION,
 			overwrite: true,
+			webhook: undefined,
 		},
 		extraContext
 	);

packages/lambda/src/test/integration/renders/transparent-webm.test.ts

@@ -62,6 +62,7 @@ test('Should make a transparent video', async () => {
 			muted: false,
 			version: VERSION,
 			overwrite: true,
+			webhook: undefined,
 		},
 		extraContext
 	);