Polling vs Webhook
When a video or image is generated using the Shotstack editing API the file is copied to the hosting and storage location asynchronously. This process normally takes a few seconds and there are two ways to know when the file is ready.
Polling the API
You can check the Serve API by polling asset
endpoint by render id. When the
status has a value of
ready then the
file has been copied and is ready to view. Not that this request may return up to 3 assets, each of which will need to
be checked. Polling is a simple way to check the status of a file but it is not the most efficient.
Receiving a webhook
Instead of polling you can request a webhook callback. The callback notifications is sent to your server with details of the transfer when it either completes or fails. To receive a webhook you add the following to the root level of the JSON render request:
https://my-server.com/webhook.php is your own URL and webhook receiving script, or subscriber.
The webhook body POSTed to your server will look like:
Note that the
id is the asset id and
render is the render id.
You may receive up to 3 callback POSTs, one for each asset, if you create a video with a thumbnail and poster image.
To learn more about setting up and using webhooks check the webhook guide in the Architecting an Application section.
Using the CDN URL without checking the status
If you know your owner id and the name of the file (you can get this from the render endpoint status request), you can also construct the URL in the correct format and use this straight away in your application. There may be a few seconds where the file is not available but if you do not need the asset to be available immediately this approach can also work.