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.

Request:

curl -H "Authorization: Uploadcare.Simple publickey:secretkey" \
     "https://api.uploadcare.com/webhooks/"

Response:

[
  {
    "id": 1,
    "created": "2016-04-27T11:49:54.948615Z",
    "updated": "2016-04-27T12:04:57.819933Z",
    "event": "file.uploaded",
    "target_url": "http://sometargeturl.com/hooks/receiver",
    "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=http://sometargeturl.com/hooks/receiver/second" \
     -d "event=file.uploaded" \
     "https://api.uploadcare.com/webhooks/"

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" \
     "https://api.uploadcare.com/webhooks/35/"

Delete a subscription

POST /webhooks/unsubscribe/

Required parameters are identical to the subscribe method.

Request example

Request:

curl -X POST \
     -H "Authorization: Uploadcare.Simple publickey:secretkey" \
     -d "target_url=http://sometargeturl.com/hooks/receiver/second" \
     -d "event=file.uploaded" \
     "https://api.uploadcare.com/webhooks/unsubscribe/"

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": [
        72,
        72
      ],
      "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": "https://ucarecdn.com/daff9fd4-9bd4-472e-a41a-438f1de41d02/001.jpeg",
    "url": "",
    "source": null,
    "variations": null,
    "rekognition_info": null
  },
  "hook": {
    "id": 751108,
    "project_id": 42797,
    "target": "https://webhook.site/715235ba-c23d-459e-b97c-6255cb98b3bf",
    "event": "file.uploaded",
    "is_active": true,
    "created_at": "2021-03-08T07:40:47.807189Z",
    "updated_at": "2021-03-08T07:40:47.807189Z"
  },
  "file": "https://ucarecdn.com/daff9fd4-9bd4-472e-a41a-438f1de41d02/001.jpeg"
}