REST API Webhooks

You can use webhooks to receive notifications about your uploads. For instance, once a file gets uploaded to your project, we can notify you by sending a message to a provided URL.

We provide the two following concepts to use with webhooks: subscription contains the target_url that we need to touch on an event and refers to how you get the info; notification holds an actual payload that is sent to active subscriptions — the info you get.

Get a list of active subscriptions

GET /webhooks/

Request example

The following example deals with requesting a list of active subscriptions for an Uploadcare project identified by the key pair. In the response, we can see there is an active event sent to a webhook-receiving URL.


curl -H "Authorization: Uploadcare.Simple publickey:secretkey" \


    "id": 1,
    "created": "2016-04-27T11:49:54.948615Z",
    "updated": "2016-04-27T12:04:57.819933Z",
    "event": "file.uploaded",
    "target_url": "",
    "project": 13,
    "is_active": true

Create a new subscription

POST /webhooks/
The following parameters are required and SHOULD be included in the request.

target_url, string

A URL that is triggered by an event, for example, a file upload. A target URL MUST be unique for each project — event type combination.

event, event type

An event you subscribe to. Presently, we only support the file.uploaded event.

is_active, boolean, optional

Marks a subscription as either active or not, defaults to true.

Takes values: 1, true, True to mark a subscription as active and 0, false or False otherwise.

Request example

Example request:

curl -X POST \
     -H "Authorization: Uploadcare.Simple publickey:secretkey" \
     -d "target_url=" \
     -d "event=file.uploaded" \

Update subscription parameters

The request is designed to modify an existing subscription.

POST /webhooks/:subscription_id/

Fields available for updating,

  • target_url
  • event
  • is_active

You can choose which fields to provide in a request. If a field is not provided, its value will not be affected. Here is an example where we only specify the is_active field.

Request example

curl -X POST \
     -H "Authorization: Uploadcare.Simple publickey:secretkey" \
     -d "is_active=true" \

Delete a subscription

POST /webhooks/unsubscribe/

Required parameters are identical to the subscribe method.

Request example


curl -X POST \
     -H "Authorization: Uploadcare.Simple publickey:secretkey" \
     -d "target_url=" \
     -d "event=file.uploaded" \

On success, the unsubscribe method returns a 204 status code without any message.

Webhooks payload

An example notification that is sent on the file.uploaded event:

  "payload_hash": "2341278228",
  "data": {
    "uuid": "daff9fd4-9bd4-472e-a41a-438f1de41d02",
    "image_info": {
      "color_mode": "RGB",
      "format": "JPEG",
      "height": 1900,
      "width": 2851,
      "orientation": null,
      "dpi": [
      "geo_location": null,
      "datetime_original": null,
      "sequence": false
    "video_info": null,
    "mime_type": "image/jpeg",
    "original_filename": "001.jpeg",
    "size": 910059,
    "is_image": true,
    "is_ready": true,
    "datetime_removed": null,
    "datetime_stored": null,
    "datetime_uploaded": null,
    "original_file_url": "",
    "url": "",
    "source": null,
    "variations": null,
    "rekognition_info": null
  "hook": {
    "id": 751108,
    "project_id": 42797,
    "target": "",
    "event": "file.uploaded",
    "is_active": true,
    "created_at": "2021-03-08T07:40:47.807189Z",
    "updated_at": "2021-03-08T07:40:47.807189Z"
  "file": ""