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,

{
  "hook": {
    "id": 2,
    "event": "file.uploaded",
    "target": "http://sometargeturl.com/hooks/receiver/second"
  },
  "data": {
    "uuid": "03ccf9ab-f266-43fb-973d-a6529c55c2ae",
    "is_image": true,
    "filename": "image.png",
    "is_stored": true,
    "done": 64819,
    "file_id": "03ccf9ab-f266-43fb-973d-a6529c55c2ae",
    "original_filename": "image.png",
    "image_info": {
      "height": 45,
      "width": 91,
      "geo_location": null,
      "datetime_original": null,
      "format": "PNG"
    },
    "is_ready": true,
    "total": 4726,
    "size": 4726
  },
  "file": "http://www.ucarecdn.com/03ccf9ab-f266-43fb-973d-a6529c55c2ae/image.png"
}