CloudConvert
API v1 is deprecated and will be turned off on January 1, 2022. Check out the API v2 documentation.

Hooks API Get notified about events

CloudConvert supports REST Hooks. By this you can register a special URL of your application and we will ping this URL on certain events. The big benefit is that your application does not need to pull for changes any more.

Subscribing for an event

POST https://api.cloudconvert.com/v1/hook 
Authorization: Bearer API_KEY

{
    "url": "https://url.to/notify",
    "event": "finished"
}

It is possible to subscribe for the following events:

Event Description
started Any conversion with your API Key was started
finished Any conversion with your API Key finished
error Any conversion with your API Key failed

Our calls to the hook

When subscribed we will do POST requests to your provided URL as shown in the following example. The payload of the request will be the current status of the conversion.

POST https://url.to/notify 
{
    "id": "v4cw72hf3",
    "url": "//srv01.cloudconvert.com/process/v4cw72hf3",
    "percent": 100,
    "message": "Conversion finished!",
    "step": "finished",
    "starttime": 1357588277,
    "expire": 1357595479,
    "output": {
        "filename": "Cloud Atlas Extended Trailer #1 (2012) HD.mp4",
        "ext": "mp4",
        "size": 10920297,
        "url": "//srv01.cloudconvert.com/download/~ugl5vnrpfO"
    },
    "endtime": 1357588279
}

If the request fails (network error) or your server returns with HTTP error >=500, we will retry the request up to 5 times with 5 seconds in between. If your subscription URL returns an HTTP error 4xx we will automatically unsubscribe and delete the hook.

List all your subscriptions

GET https://api.cloudconvert.com/v1/hooks 
Authorization: Bearer API_KEY
[
  {
    "id": "1",
    "url": "https://url.to/notify",
    "event": "finished"
  }
]

Unsubscribe

DELETE https://api.cloudconvert.com/v1/hook/1 
Authorization: Bearer API_KEY