Webhook notifications

Event types

Available event types:

Notes:

• file.infected will be deprecated in the next API version in favor of file.info_updated.
• REST API v0.6 supports only the file.uploaded event.

{
  "hook": {
    "event": "file.info_updated"
    ...
  },
  "data": {
    "appdata": {
      "uc_clamav_virus_scan": {
        "data": {
          "infected": true,
          "infected_with": "Win.Test.EICAR_HDB-1"
        },
        "version": "0.104.3",
        "datetime_created": "2021-09-21T11:24:33.159663Z",
        "datetime_updated": "2021-09-21T11:24:33.159663Z"
      }
    }
    ...
  },
  "previous_values": {
    "appdata": {
      "uc_clamav_virus_scan": {
        "data": {
          "infected": false
        },
        "version": "0.104.2",
        "datetime_created": "2021-09-21T11:24:33.159663Z",
        "datetime_updated": "2021-09-21T11:24:33.159663Z"
      }
    }
  }
}

{
  "hook": {
    "event": "file.deleted",
    /* REST HOOK FIELDS */
  },
  "data": {
    "datetime_removed": "2019-07-15T14:41:10.000000Z"
    /* REST FILE FIELDS */
  }
}

{
  "hook": {
    "event": "file.stored"
    /* REST HOOK FIELDS */
  },
  "data": {
    "datetime_stored": "2018-11-26T12:49:10.477888Z"
    /* REST FILE FIELDS */
  }
}

{
  "hook": {
    "event": "file.infected"
    /* REST HOOK FIELDS */
  },
  "data": {
    "appdata": {
      "uc_clamav_virus_scan": {
        "data": {
          "infected": true,
          "infected_with": "Win.Test.EICAR_HDB-1"
        },
        "version": "0.104.3",
        "datetime_created": "2021-09-21T11:24:33.159663Z",
        "datetime_updated": "2021-09-21T11:24:33.159663Z"
      }
    }
    /* REST FILE FIELDS */
  },
}

Webhook payload structure

Regardless of the event type, the webhook payload object has the following common properties:

Check out webhook API reference to see callback schemas for different events.

Identifying event cause

The field initiator identifies the source or cause of the event that triggered the webhook. It contains type and detail.

{
  "initiator": {
    "type": "addon",
    "detail": {
      "addon_name": "zencoder_convert_video",
      "request_id": ":request_id",
      "source_file_uuid": ":UUID"
    }
  }
}

type:

• addon — an event initiated by one of the add-ons (e.g. video encoding).
• api — initiated by any other API request (e.g. file upload).
• system - initiated by our platform (e.g. file expired and was removed automatically)

detail:

• addon_name — if type is addon, then an additional field will tell you what exact add-on it was.
• request_id — a reference to the request in access logs (null, if initiator is system).
• source_file_uuid — if the file is derivative (e.g. encoded from another video file), it will provide its UUID.

This information provides context and information about the event, such as who or what caused it and what action was taken. This is useful for developers who want to automate certain tasks based on specific events or conditions.

For example, if a new file was uploaded as a result of background removal, the initiator field can be used to identify the add-on that triggered the event. Use it to notify a specific user or update a database with new information.

Explore the callback section in webhooks API reference to learn more about it.

Usecase example

For example, you want to set up a user-generated content moderation system.

When a third-party user uploads a file, you want to ensure that the file does not contain viruses or inappropriate content such as violence or drugs.

To check files, you need to:

• Create a handler that accepts the webhook when a file is uploaded. Virus scanning is automatically launched during the upload process, so no additional actions are required.
• Create a handler to receive the webhook in case a virus is detected by malware protection system.
• Create a handler that accepts the webhook when the file information is updated. Depending on your goals, this handler can process the received information using logical statements to determine which type of data is sensitive.

The previous_values object provides information about the type of data that was updated. By examining the keys within previous_values.appdata, you can determine what information was added (if the value is null) or updated (if the value is not null).

To determine if an image contains something that you would like to avoid, you can perform a simple check:

moderation_labels = appdata['aws_rekognition_content_moderation']['ModerationLabels']
for label in moderation_labels:
    if label["ParentName"] == "Tobacco Products" and label["Confidence"] > 50:
        # Do something

Next, launch the unsafe content detection. Once the processing is finished, the moderation labels will be added to the file's application data and the webhook will be sent.

Then you can decide which action is required in such a case. For example, the file can be removed.

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:

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.

Signed webhooks

Each webhook payload can be signed with a secret to ensure that the request comes from the expected sender. The resulting signature is included in the request header, so you can use it to validate that the request comes from Uploadcare.

curl -v -X POST -H "Content-Type: application/json"
-H 'Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY' 'https://api.uploadcare.com/webhooks/WEBHOOK_ID/'
-d '{"signing_secret": "some-secret"}'

curl -v -H 'Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY' 'https://api.uploadcare.com/webhooks/'

export UC_SIGNING_SECRET=your_signing_secret

import hashlib
import hmac
import os

UC_SIGNING_SECRET = os.environ['UC_SIGNING_SECRET']

# see payload example in callbacks section of
# https://uploadcare.com/api-refs/rest-api/v0.7.0/#operation/webhookCreate
webhook_body = '''{...}'''

# example of a X-Uc-Signature HTTP header value
x_uc_signature_header = (
    "v1=f4d859ed2fe47b9a4fcc81693d34e58ad12366a841e58a7072c1530483689cc0"
)
calculated_signature = (
    "v1="
    + hmac.new(
        UC_SIGNING_SECRET.encode("utf-8"),
        webhook_body.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()
)
print("x_uc_signature_header", x_uc_signature_header)
print("calculated_signature", calculated_signature)

if calculated_signature in x_uc_signature_header:
    print("WebHook signature matches!")
else:
    print("WebHook signature mismatch!")

API integrations

You don't have to code most of the low-level API integrations. We have high-level libraries for all popular platforms:

• JavaScript
• PHP
• Python & Django
• Ruby
• Rails
• Java
• Golang
• Rust
• Swift
• Android