Webhooks
On this page
Uploadcare uses webhooks to notify your application about certain events that occur in your project asynchronously. For example, you may need to add or update a record in your database when a new file has been uploaded. When an event happens, we'll make a POST request with a JSON payload to the endpoint you provided.
If Uploadcare doesn't receive a 2xx
response from your system,
we will try to deliver the message for the next 72 hours,
increasing the delay between attempts.
Event types
Righ now there are two available event types:
Event | Description | REST API v0.6 | REST API v0.7 |
---|---|---|---|
file.uploaded | A new file has been uploaded to the project | ✅ | ✅ |
file.infected | ClamAV detected a virus in a file | ❌ | ✅ |
More event types will be added in the next REST API updates.
file.uploaded
Fires when a new file is uploaded to the project or when a new file
is created by executing on of the following add-ons.
Copying a file locally also triggers
the file.uploaded
event.
file.infected
It fires when an infected file is detected. It may occur when a newly uploaded file is scanned automatically or when you explicitly perform a scan on an existing file with the Virus checking add-on.
Configuring endpoints
Endpoints can be configured in the dashboard or via the REST API. We recommend using the UI in the Webhooks section as a more convenient option.
Enter a URL of your webhook endpoint that Uploadcare will send notifications to.
If you want Uploadcare to sign the requests, enter a signing secret key. See Signed webhooks for more details.
Also, you'll be prompted to choose the API version. Depending on the version, different sets of events will be available for subscription. The later the version, the more events it supports. The payload structure also depends on the API version. Consider using the latest API version whenever possible.
The same webhook endpoint can be added multiple times to receive notifications about different events. Also, you can add multiple different endpoints for the same event type.
Handling requests from Uploadcare
Uploadcare will submit requests to your app's webhook endpoint, which is no different from any other route in your application. When your application receives a request from Uploadcare, it can do various things, like adding a record about a newly uploaded file to your database or other types of tasks.
When configuring your webhook receiver, keep in mind that if your
server doesn't respond with 2xx
, the request attempt will timeout
after one minute, and our system will retry it.
Here's how the retry mechanism works:
Retry # | Timing |
---|---|
Retry #1 | 1 minute after the first attempt |
Retry #2 | 5 minutes after the first attempt |
Retry #3 | 10 minutes after the first attempt |
Retry #4 | 30 minutes after the first attempt |
Retry #5 | 60 minutes after the first attempt |
Retry #6 and further | Once an hour within 72 hours |
If you expect this to cause problems in your workflow, consider
doing the work in an asynchronous task so that your application
can immediately respond with a 2xx
to the request.
Handling webhooks locally
If your application runs on a local machine, and its webhook endpoints
have URLs like https://localhost:3000/hooks
, you'll
need to create a secure tunnel to this port on your machine to expose
it to the Internet.
Consider using Ngrok or similar tools to accomplish this.
We recommend setting up separate projects for the development/staging/production environments and configuring webhooks accordingly.
Webhook payload structure
Regardless of the event type, the webhook payload object has three common properties:
Key | Type | Description |
---|---|---|
hook | object | Contains information about the webhook, event, and the project |
data | object | Contains information about the file the event occured with |
file | string | Contains a CDN URL of the file the event occured with |
Payload example
The following is an example of a webhook payload for the file.uploaded
event (API v0.7):
{
"hook": {
"id": 1446695,
"project_id": 42797,
"project_pub_key": "3a8b234aef4a1d339b88",
"target": "https://webhook.site/0dc52067-db2f-4698-a2b6-80ac9313113d",
"event": "file.uploaded",
"is_active": true,
"version": "0.7",
"created_at": "2023-01-18T10:34:05.246676Z",
"updated_at": "2023-01-18T10:34:05.246676Z"
},
"data": {
"content_info": {
"mime": {
"mime": "application/zip",
"type": "application",
"subtype": "zip"
}
},
"uuid": "620ff227-eb36-460f-a809-8ba1ea98b1f3",
"is_image": false,
"is_ready": true,
"metadata": {},
"appdata": {
"uc_clamav_virus_scan": {
"data": {
"infected": true,
"infected_with": "Win.Test.EICAR_HDB-1"
},
"datetime_created": "2023-01-18T13:01:24.911818Z",
"datetime_updated": "2023-01-18T13:01:24.911842Z",
"version": "0.105.1"
}
},
"mime_type": "application/zip",
"original_filename": "eicarcom2.zip",
"original_file_url": "https://ucarecdn.com/620ff227-eb36-460f-a809-8ba1ea98b1f3/eicarcom2.zip",
"datetime_removed": null,
"size": 308,
"datetime_stored": "2023-01-18T13:01:24.807375Z",
"url": "https://api.uploadcare.com/files/620ff227-eb36-460f-a809-8ba1ea98b1f3/",
"datetime_uploaded": "2023-01-18T13:01:24.64201Z",
"variations": null
},
"file": "https://ucarecdn.com/620ff227-eb36-460f-a809-8ba1ea98b1f3/eicarcom2.zip"
}
json
Difference between v0.6 and v0.7
Depending on the version, the data
object in the payload will have
a different structure. When using v0.7, the data
object will have
three additional keys: appdata
, content_info
, metadata
.
Key | Type | Description |
---|---|---|
appdata | object | Contains information updated when Add-ons are launched: antivirus, object rekognition, background removal |
content_info | object | Contains information about the file type. The object will include detailed image/video metadata for images and videos |
metadata | object | Contains custom metadata keys. See Metadata for more details |
Signed webhooks
There is an option to verify webhook requests that Uploadcare sends to your endpoint. This is achieved by including a signature in the request's header. You can use this signature to ensure that the request was sent by Uploadcare and not an attacker attempting to spoof your endpoint.
API integrations
You don't have to code most of the low-level API integrations. We have high-level libraries for all popular platforms: