Webhooks

Webhook events

CloudConvert can notify your application about the status of jobs. You can create and manage your webhooks on the CloudConvert dashboard.

Available Webhook Events

job.created Emitted when a new job was just created.
job.finished A job (and all associated tasks) completed successfully. The payload includes the job as shown by the example payload on the right.
job.failed A job failed.

Error Handling

If the request fails (network error) or your server returns with HTTP error >=500, we will retry the request 3 times while waiting some time in between. If your webhook URL returns an HTTP error 410 (Gone) we will automatically disable the webhook. You can reenable the webhook on the CloudConvert dashboard.

If your webhook is failing you will receive an email notification.

Signing

Our requests are cryptographically signed. If you receive a webhook, you should validate it to make sure it comes from us. Each webhook has a unique signing secret. You can show the signing secret in your webhook settings using the button.

The CloudConvert-Signature header contains a hash-based message authentication code (HMAC) with SHA-256.

As an example, the following PHP function call calculates the signature for validation:

$signature = hash_hmac('sha256', $payload, $signingSecret);

$payload is the full request body (the JSON string) of our request to the webhook URL. You can find the $signingSecret for your webhook in your webhook settings.

Webhook Request

POST https://your-webhook/endpoint

Headers

Content-Type: application/json
CloudConvert-Signature: 363495aa6b142fa06a3015aa7cb53fec870ebece9fa7cc35b99409685ba250da

Example Payload

{
  "event": "job.finished",
  "job": {
    "id": "4b6ee8e2-e293-4805-b48e-a03876d1ec66",
    "tag": "myjob-123",
    "status": null,
    "created_at": "2019-04-13T21:18:47+00:00",
    "started_at": null,
    "ended_at": null,
    "tasks": [
      {
        "id": "acdf8096-10a1-4ab7-b009-539f5f329cad",
        "name": "export-1",
        "operation": "export/url",
        "status": "finished",
        "message": null,
        "percent": 100,
        "result": {
          "files": [
            {
              "filename": "file.pdf",
              "url": "https://storage.cloudconvert.com/eed87242-577e-4e3e-8178-9edbe51975dd/file.pdf?temp_url_sig=79c2db4d884926bbcc5476d01b4922a19137aee9&temp_url_expires=1545962104"
            }
          ]
        },
        "created_at": "2019-04-13T21:18:47+00:00",
        "started_at": "2019-04-13T21:18:47+00:00",
        "ended_at": "2019-04-13T21:18:47+00:00",
        "depends_on_task_ids": [
        ],
        "links": {
          "self": "https://api.cloudconvert.com/v2/tasks/acdf8096-10a1-4ab7-b009-539f5f329cad"
        }
      }
    ],
    "links": {
      "self": "https://api.cloudconvert.com/v2/jobs/4b6ee8e2-e293-4805-b48e-a03876d1ec66"
    }
  }
}

Create webhooks

Create a webhook. Requires the webhook.write scope.

Arguments
url string, required The URL to send the notifications to.
events array, required Select the events. See the available events here.

Returns

The created webhook. See example on the right.

Endpoint

POST https://api.cloudconvert.com/v2/webhooks

Example Request

$ curl -X POST "https://api.cloudconvert.com/v2/webhooks" \
       -H "Authorization: Bearer API_KEY" \
       -H "Content-type: application/json" \
       -d '{
  "url": "https://mywebhook/cloudconvert",
  "events": [
    "job.failed",
    "job.finished"
  ]
}'

Example Response

{
  "data": {
    "id": 4354367,
    "url": "https://mywebhook/cloudconvert",
    "disabled": false,
    "events": [
      "job.failed",
      "job.finished"
    ],
    "failing": false,
    "signing_secret": "XXXXXXXXXXXXXXX",
    "created_at": "2019-06-23T15:11:07+00:00",
    "updated_at": "2019-06-23T15:11:07+00:00",
    "links": {
      "self": "https://api.cloudconvert.com/v2/webhooks/4354367"
    }
  }
}

Lists webhooks

List all webhooks. Requires the webhook.read scope.

Query Parameters
filter[url] string, optional The result will be filtered to include only webhooks with a specific URL.
per_page boolean, optional Number of webhooks per page, defaults to 100.
page boolean, optional The result page to show.

Returns

The list of webhooks. You can find details about the webhook model response in the documentation about the show webhooks endpoint.

Endpoint

GET https://api.cloudconvert.com/v2/users/me/webhooks

Example Request

$ curl -g "https://api.cloudconvert.com/v2/users/me/webhooks" \
       -H "Authorization: Bearer API_KEY"

Example Response

{
  "data": [
    {
      "id": 4354367,
      "url": "https://mywebhook/cloudconvert",
      "disabled": false,
      "events": [
        "job.failed",
        "job.finished"
      ],
      "failing": true,
      "last_error_at": "2019-08-13T13:12:19+00:00",
      "last_response_code": "NETWORK_ERROR",
      "signing_secret": "XXXXXXXXXXXXXXX",
      "created_at": "2019-06-23T15:11:07+00:00",
      "updated_at": "2019-06-23T15:11:07+00:00",
      "links": {
        "self": "https://api.cloudconvert.com/v2/webhooks/4354367"
      }
    }
  ],
  "links": {
    "first": "https://api.cloudconvert.com/v2/webhooks?page=1",
    "last": null,
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "path": "https://api.cloudconvert.com/v2/webhooks",
    "per_page": 100,
    "to": 2
  }
}

Delete a webhook

Delete a webhook. Requires the webhook.write scope.

Returns

An empty response with HTTP Code 204.

Endpoint

DELETE https://api.cloudconvert.com/v2/webhooks/{ID}

Example Request

$ curl -X DELETE "https://api.cloudconvert.com/v2/webhooks/456467" \
       -H "Authorization: Bearer API_KEY"