Webhooks

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: