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
- Create a new subscription, POST
- Update subscription parameters, POST
- Delete a subscription, POST
- Webhooks payload
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/
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"
}