iconik Webhooks

Get notifications on events happening within iconik

Webhook Introduction

Webhooks are a powerful way to create functionality that happens, triggered by events in iconik. You can build functionality that triggers metadata changes, transcode operations and more when a predefined action occurs.

The following is a list of typical use-cases:

  • On doing video analysis trigger metadata changes or parsing.
  • After transcoding has happened, trigger video analysis
  • On asset import, automatically trigger adding to collections, discovery or metadata changes
  • When metadata has changed, change the access rights.
  • On asset being approved by everyone in the review, move to a shared collection.
  • Make requests for a file being placed on a server, after it has been added to a certain collection.

The Webhooks are not also limited to just one resulting action, you could of course trigger change of metadata, add to collection and change ACL after an asset has been transcoded.

It is also not restricted to operations just within iconik, for instance after getting a webhook notification that an asset is approved, you could then trigger your access to your storage bucket, setting an ACL on the object, and then use that object in an external system, or copy the object to another service somewhere.

Table of Contents

Getting Started REST API Overview REST API Reference Guide REST API Swagger Definitions Webhooks iconik Storage Gateway iconik Portal Sync Security Guidelines

How Webhooks work.

The basis of webhooks is that after an event happening to an iconik entity we can trigger a HTTP/HTTPS call to a service of your choice.

That HTTP call is made with a payload containing information about what has happened. This will be in JSON format.

As iconik is cloud based, the notifications will come from the cloud and we expect to call a service that is publically accessible.

Iconik is then configured that on a type of event, with an operation, within a certain realm we will call a URL.

The URL should return a standard HTTP Status Code, and that URL could then run any script or service of your choosing. What you choose to run could be the following:

  • Hosted server running a web application
  • Cloud function, such as AWS Lambda or Google Cloud Functions

If you don't have a web server running on the internet, and don't wish to set one up we would recommend using Cloud functions.

Partner Content

PVT has created a guide on setting up iconik Webhooks to automatically use video intellegence analysis after an asset has been transcoded.

Setting up WebHooks

Webhooks can either by setup using the notifications/ API or by using the Admin pages in the web interface.

Using the web interface, login with someone with admin role or the rights to create web-hooks. Navigate to Settings then to Webhooks. And you will be shown a list (which might be empty) and a form with which you can create a new webhook that will be called.

Here is the definitions for the fields:

Type
The entity type that you wish to get a notification on.
Operation
After which operation such as CREATE, UPDATE, DELETE do you wish to be notified on.
Realm
The sub-resource type that the notification must match to trigger the webhook.
Query
The query that the notification must match to trigger the webhook. Examples:
  • realm="metadata"
  • data.is_archived != true
  • data.metadata.storage_id = "5636faac-cded-11eb-be60-ded06465c664"
  • event_type = "assets" OR event_type = "collections"
  • data.user=null AND data.is_archived=true AND (data.status!="CLOSED" OR data.size>=10)
URL
Your URL that will be called when this is triggered.

Once you press Add, your webhook is configured and will be called on the next time an event matches the profile that is created, calling your URL.