WebHooks

Webhooks are used for calling URLs when an action has occurred within iconik.

Webhook Definitions

Webhook definitions store what action the webhook will be called on, what must be matched and what URL to call.

Webhook Types

These are the types that actions must occur on for a webhook to be called.

Webhook Operation

These are the operation types that will cause a webhook to be called:

All.
Create.
Delete.
Purge.
Restore.
Update.
Download (For Assets only)

Webhook Realm

This is what must have occurred within the type.

Webhook URL

This is the URL you provide that will be called.

Webhook Status

This is the status of the webhook. If calling the webhook keeps failing the status will automatically be set to failed.

Webhook Query

In order to lower load on your webhook listening service and listen to the events that you really interested in you can use a newly introduced query language. If this field is not empty iconik will check if the webhook event matches the query and will call webhook URL only if it does, otherwise the event will be ignored. Query language allows to filter on the information that exists on the webhook's event itself, so a webhook listens to a FILES realm it will be possible to filter on fields that exist on a file and won't be possible to filter by asset's name for example. Language support simple data types like number, string, bool, null as a well nested data types like array and dictionary. To filter events you need to specify a field name, comparison operator and a value that you are interested in. The simples example would be filtering events by operation operation="update". The following comparison operators are supported: =, !=, <, >, <=, >=. In instances where exact string matching is not feasible, regular expressions (//) can be employed. To construct more intricate queries, utilize boolean operators AND, OR, and parentheses (( and )).

Let's imagine that there is a webhook in a system that listens for assets event type and realm metadata. In such case everytime a metadata gets changed your webhook's URL will be called with the data like this:

{
    "system_domain_id": "1297c8b6-3563-11e7-adf1-6c4008b85488",
    "object_id": "1fa53a56-932d-11ed-9b47-7a40066d5234",
    "user_id": "1fb4c6f8-cded-11eb-b943-669489a791b1",
    "realm": "metadata",
    "operation": "update",
    "data": {
        "metadata_values": {
            "share": {
                "date_created": "2023-02-02T14:42:51.717840+00:00",
                "field_values": [{"value": "true"}]}
            },
            "version_id": "1fa5d93e-932d-11ed-9b47-7a40066d5234",
            "object_id": "1fa53a56-932d-11ed-9b47-7a40066d5234",
            "object_type": "assets"
        },
    "request_id": "4fac93061907199631ae3deb1979a5ad"
}

As you can see there are some webhook's related information like realm, operation, object_id on the top level of the document which makes it possible to filter on these fields too. Here is an example of filtering metadata changes made by a specific user user_id="9b219676-7567-11e9-806b-62fe166f0ad7" In case you need to filter by a field that is located deeper in the document the "dot" (.) operator should be used. Here is an example data.metadata_values.share.field_values.value="true"

Let's take a look at another example

{
    "system_domain_id": "1297c8b6-3563-11e7-adf1-6c4008b85488",
    "object_id": "918728e2-bc1c-11ed-aaef-66cff3148306",
    "user_id": null,
    "realm": "formats",
    "operation": "update",
    "data": {
        "deleted_by_user": null,
        "status": "ACTIVE",
        "metadata": [
            {
                "format": "MPEG-4",
                "internet_media_type": "video/mp4",
                "overall_bit_rate_mode": "VBR",
                "overall_bit_rate": "16223680",
                "frame_rate": "25.000",
                "frame_count": "276",
                "size": "0"
            }
        ],
        "storage_methods": [
            "GCS"
        ],
        "archive_status": "NOT_ARCHIVED",
        "is_online": false,
        "user_id": "fe10607e-b4a4-11e7-a283-0a580a300758",
        "name": "PPRO_PROXY",
        "date_deleted": null,
        "version_id": "9187bd48-bc1c-11ed-aaef-66cff3148306",
        "components": [
            {
                "type": "VIDEO",
                "name": "VIDEO",
                "id": "e33e13e4-bc1c-11ed-a6cf-1e18a8d37b7d",
                "metadata": {
                    "format": "AVC",
                    "internet_media_type": "video/H264",
                    "duration": "11040",
                    "bit_rate_mode": "VBR",
                    "bit_rate": "16087577",
                    "width": "3840",
                    "height": "2160",
                    "frame_rate": "25.000"
                }
            },
            {
                "type": "AUDIO",
                "name": "AUDIO",
                "id": "e33e1bd2-bc1c-11ed-a6cf-1e18a8d37b7d",
                "metadata": {
                    "format": "AAC",
                    "duration": "11040",
                    "source_duration": "11061",
                    "bit_rate": "127878",
                    "channel_s": "2"
                }
            }
        ],
        "id": "ac5149b4-bc1c-11ed-a6cf-1e18a8d37b7d",
        "asset_id": "918728e2-bc1c-11ed-aaef-66cff3148306"
    },
    "request_id": "476117422b18ed2f915fe9887b77b702"
}

Here is how to trigger a webhook for AVC or MPEG-4 formats that are active and online:

data.status="ACTIVE" AND data.is_online=true AND (data.components.metadata.format="AVC" OR data.components.metadata.format="MPEG-4")

Trigger only if deleted_by_user field is set to null or it doesn't exist:

data.deleted_by_user=null

A webhook with the following query will be triggered if width or height is greater than or equal 1920 and a duration is longer than a minute (60000ms):

(data.components.metadata.width>=1920 OR data.components.metadata.height>=1920) AND data.components.metadata.duration>60000

Note that in the previous example we used 1920 and 60000 without quotes so iconik tries to convert string values (like the one we have in the event "width": "3840",) to a number and then compare it to the value from query. On the other hand this query data.components.metadata.width>="1920" doesn't make any sense and won't work because string don't support <, >, >=, <= operators.

To apply pattern-based filtering, one can utilize regular expression operators (regex). Here is an example:

When filtering string values, it is often customary to use double quotes ("") to specify exact values. However, in certain cases, this approach may not be flexible enough. In such situations, regular expressions can be used instead. Simply enclose your regular expression in forward slashes (//), like so: field_name=/(d+)/.

If you want a webhook to be triggered for formats such as MPEG-2 or MPEG-4, you can use the following query: data.components.metadata.format=/MPEG-[2,4]/.

API Links