CloudConvertdocs
API Reference

Webhooks

Create, list and delete 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 events

EventDescription
job.createdEmitted when a new job was just created.
job.finishedA job (and all associated tasks) completed successfully. The payload includes the job as shown by the example payload below.
job.failedA job failed.

Our webhook request

POSThttps://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"
    }
  }
}

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.

Create webhook

Create a webhook via API.

POSThttps://api.cloudconvert.com/v2/webhooks

Authentication

Authorization
header required
The Authorization header expects a Bearer token with the webhook.write scope.

Body

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

Example Body

{
  "url": "https://mywebhook/cloudconvert",
  "events": [
    "job.failed",
    "job.finished"
  ]
}

::

Response

The created webhook:

id
integer
The ID of the webhook.
url
string
The URL of the webhook.
disabled
boolean
Whether the webhook is disabled.
events
array
The events the webhook is subscribed to.
failing
boolean
Whether the webhook is currently failing.
signing_secret
string
The signing secret for validating webhook requests.
created_at
string
ISO8601 timestamp when the webhook was created.
updated_at
string
ISO8601 timestamp when the webhook was last updated.

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"
    }
  }
}

Dynamic webooks

When creating a job, you can set a webook_url parameter. This results in webook notifications to the specified URL for the single job only.

List webhooks

List all webhooks.

GEThttps://api.cloudconvert.com/v2/users/me/webhooks

Authentication

Authorization
header required
The Authorization header expects a Bearer token with the webhook.read scope.

Query Parameters

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

Response

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

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 webhook

Delete a webhook.

DELETEhttps://api.cloudconvert.com/v2/webhooks/{ID}

Authentication

Authorization
header required
The Authorization header expects a Bearer token with the webhook.write scope.

Response

An empty response with HTTP Code 204.

Users

Show information about the current user and the remaining credits.

Socket API

Real-time task updates using Socket.io.