Video delivery

Once a render is complete, the final video becomes available for delivery and access through several flexible methods. Whether you’re building automated workflows or handling video manually, Plainly supports a variety of delivery options tailored to different needs.

Before a video is available, it goes through a processing pipeline after the render is submitted. This pipeline includes validating inputs, allocating rendering resources, rendering the video with the dynamic data, and finalizing the output. Once the video file is ready, it’s uploaded to the Plainly cloud storage and made accessible through the methods listed below.

Manual download Integrations Webhook notifications Static link sharing

Video expiration

Videos are stored in Plainly cloud storage for a limited time, which is defined by video retention period of your subscription package. After this period, the video will be deleted and will no longer be accessible.

If you need to keep the video for a longer period, you can download it or store it in your own cloud storage.

Manual download

The simplest way to access your rendered video is through the Plainly app. Once the render is complete, you can download the video directly from the Render details page. This page provides a summary of a render, including all output files like video file, thumbnail images, etc.

Render details can be access from the Renders page , which lists all your renders and is filterable by project, template, render state or custom search criteria.

In case of the batch rendering you can download all the rendered videos at once by visiting the Batch download page.

Integrations

Controlling video delivery through integrations is achieved by setting up a video distribution integration type. Read more in the Video distribution section.

Webhook notifications

If you want to get notified when the render is done, you can set up a webhook notification. Webhook is a URL that you can pass to Plainly when invoking a render, and once the render is finalized we will send a POST request to that URL with the result of the rendering process.

When passing the webhook information, beside the URL you can include additional properties and options:

Url - The HTTP(S) webhook URL to execute the POST call once the rendering is finished.
Passthrough - Pass through value for the webhook.
On failure - Should webhook be called also on the failed renders.
On invalid - Should webhook be called also on the invalid renders.

If on invalid parameter is not explicitly set, the value of the on failure parameter will be used instead in order to decide if the webhook should be called on the invalid renders.

Webhook security

If you are on one of the enterprise plans and you need increased security for the webhook calls coming from the Plainly infrastructure, you can request a static IP that will be used to execute requests against your HTTP endpoint.

API cURL example - Create render with webhook specification


curl -X POST \
  -H "Content-Type: application/json" \
  -u "[API_KEY]:" \
  -d '{
        "projectId": "[PROJECT_ID]",
        "webhook": {
          "url": "https://example.com/webhook",
          "passthrough": "customer_id=12345",
          "onFailure": true,
          "onInvalid": false
        }
      }' \
  https://api.plainlyvideos.com/api/v2/renders

Passthrough

Note that webhook passthrough value is not mandatory, and it can be used to pass any additional information that you want to receive back in the webhook payload.

It’s a string value that can contain references to your own data, like a customer or product ID you are creating a video for.

In addition, it’s possible to send complete JSON objects as a passthrough value, but in that case you need to URL encode or string escape the JSON string before passing it to Plainly. In that case you will need to decode back the JSON string in your webhook handler.

Reference render parameters in a passthrough

A webhook passthrough can also be dynamic. This can achieved by referencing a render parameter value. For example, setting the Passthrough to:


customer:{{customerName}}

Will take value of a customerName (mandatory) render parameter. Thus, you could get a passthrough values like customer:John Doe or customer:Jane Smith.

API cURL example - Create render with webhook containing complex passthrough


curl -X POST \
  -H "Content-Type: application/json" \
  -u "[API_KEY]:" \
  -d '{
        "projectId": "[PROJECT_ID]",
        "webhook": {
          "url": "https://example.com/webhook",
          "passthrough": "{\"customerId\": \"12345\", \"productId\": \"67890\"}"
        }
      }' \
  https://api.plainlyvideos.com/api/v2/renders

Webhook delivery

The delivery on the provided webhook URL will be done automatically in the following fashion:

A webhook HTTP(S) call expects a 2xx status code in order to be marked as successful.
In case of a failed delivery, Plainly will attempt to re-call your webhook for up to one day in space of 15 minutes.
A webhook HTTP(S) request has a timeout of 30 seconds.
A webhook HTTP(S) request does follow redirects.

Once the rendering state is finalized successfully, a POST HTTP request will be sent to webhook URL containing the following body:

Successful render webhook payload


{
	"renderingId": "e1b6334e-53aa-4ac4-a08b-7975e7ce7249",
	"projectId": "56a25886-ede2-4cfc-83be-d40dd60802e8",
	"success": true,
	"output": "https://storage.plainlyvideos.com/56a25886/e1b6334e.mp4",
	"outputWatermark": "https://storage.plainlyvideos.com/56a25886/e1b6334e-watermark.mp4",
	"thumbnailUris": [
		"https://storage.plainlyvideos.com/56a25886/e1b6334e/1.png",
		"https://storage.plainlyvideos.com/56a25886/e1b6334e/2.png"
	],
	"projectZipUrl": "https://storage.plainlyvideos.com/56a25886/e1b6334e/project.zip",
	"passthrough": "This is a pass through value",
	"error": null,
	"projectName": "Project name",
	"templateName": "Template name",
	"expirationDate": "2024-12-31T23:59:59Z"
}

If webhook options allow the delivery in case of a failed or invalid renders, the payload sent will be slightly different, as it will not contain the output information and error property will contain the error details:

Failed render webhook payload


{
	"renderingId": "e1b6334e-53aa-4ac4-a08b-7975e7ce7249",
	"projectId": "56a25886-ede2-4cfc-83be-d40dd60802e8",
	"success": false,
	"output": null,
	"outputWatermark": null,
	"thumbnailUris": [],
	"projectZipUrl": null,
	"passthrough": "This is a pass through value",
	"error": {
		"message": "An error occurred during rendering",
		"code": "RENDER_ERROR"
	},
	"projectName": "Project name",
	"templateName": "Template name",
	"expirationDate": null
}

Test webhook payload

Plainly provides an endpoint where you can ask for an example webhook payload to be sent to your webhook URL. This is useful for testing purposes, and you can use it to test your webhook handler.

Check the Webhook test API reference for more information.

Only available on certain Plainly subscription plans.

Sharing links enable you to have static, non-changeable, links for videos rendered in your projects. Since every video rendered has its own unique link where it can be downloaded, this feature enables you to have a single link for each project and template. Sharing can operate in two modes:

Automatic latest promotion - this mode will always promote the latest successfully rendered video for the given template to the shared link automatically.
Manual promotion - you explicitly select videos you want to promote to the shared link.

You can enable sharing by clicking on the Enable sharing button in the Project details page. Sharing can be enabled only for the complete project and will affect all templates. The sharing link for each template can be found in the Template details page.

Please note that sharing links will become nonfunctional if:

Sharing is disabled for a project, or a project is deleted
A template is deleted (only affects a link for that single template)

Sharing is currently only supported for the .mp4 video format.