Skip to main content

Ingest: Polling vs Webhook

Ingesting files from URLs, direct uploads and processing renditions can take several seconds and sometimes minutes. There are two ways to know when the file transfer or processing is complete; polling the API or receiving a webhook.

Polling the API​

You can check the status by polling the source file details with the source Id. When the status of the source file is ready then the file is ready to be used in an edit or to be used to create a rendition. You can also see the rendition status using the same endpoint request. Polling is a simple way to check the status of files but it is not the most efficient.

Receiving a webhook​

Instead of polling you can request a webhook callback. The webhook callback is sent to your server with details of the ingested file transfer, direct upload or rendition status and whether it succeeds or fails. To receive a webhook you add the following to the root level of the JSON ingest request:

"callback": "https://my-server.com/webhook.php"

Where https://my-server.com/webhook.php is your own URL and webhook receiving script, or subscriber.

The upload or transfer of a source file to Shotstack will look like this:

{
    "type": "ingest",
    "action": "source",
    "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
    "owner": "5ca6hu7s9k",
    "status": "ready",
    "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
    "error": null,
    "completed": "2023-01-02T01:47:37.260Z"
}

A notification is also sent for each rendition and will look like this:

{
    "type": "ingest",
    "action": "rendition",
    "id": "zzyap2eg-3ae4-8p0o-xxja-5o71wq1vjat3",
    "owner": "5ca6hu7s9k",
    "status": "ready",
    "url": "https://shotstack-ingest-api-v1-renditions.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyap2eg-3ae4-8p0o-xxja-5o71wq1vjat3.mp4",
    "error": null,
    "completed": "2023-01-02T01:47:46.340Z"
}

To learn more about setting up and using webhooks check the webhook guide in the Architecting an Application section.