Overview of a Webhook and its payloads and events in Assets Server

This article provides an overview of the structure of a Webhook for Assets Server, and its payloads and events.

Webhooks

A Webhook in Assets Server consists of the following information:

• A unique ID.

• A name.

• The URL to which the event payload is sent.

• A list of Event Types which defines the events the Webhook is subscribed to.

• (Optional and applies only to asset events — see Events later in this article) A list of metadata fields of which at least one should have changed before the Webhook is triggered for an asset.

• (Optional and applies only to asset events — see Events later in this article) A list of folders and a query. The Webhook is only triggered for assets that are located in the specified paths and which meet the criteria of the query.

• A boolean stating whether the Webhook is enabled. Disabled Webhooks do not receive updates.

• A Secret Token generated by Assets Server. This can be used to verify the integrity of messages on the receiving side of the Webhook. For more information, See Securing Webhooks in Assets Server.

• An optional list of metadata fields, which will be returned with every event payload.

A Webhook may look as follows:

 [
    {
        id: "2n-UzMFgate9nAwg8zLXCs",
        url: "http://localhost:8081/",
        eventTypes: [
            "asset_rename",
            "asset_update_metadata"
        ],
        metadataToReturn: [
            "filename",
            "status"
        ],
        triggerMetadataFields: ["filename"]
        foldersAndQuery: {folders: ["nature"], query: "filename:flowers*"}
        enabled: true,
        secretToken: "8/+6zgwqUERB1q1oS3Xhxw=="
    }
]

Events

When configuring a Webhook you can choose which events you would like to receive payloads for.

The following table shows the supported event types:

Payloads

Every category of events has its own payload structure, containing relevant information about the event.

Additionally, a special X-Hook-Signature header is added to each HTTP request, which contains an HMAC hex digest of the payload.

Every event payload contains the following information:

• A timestamp in Epoch-format.

• The type of event that has occurred.

In addition, every category of events contains its own set of specific information.

Asset events

For events related to assets, the following information is sent:

• The ID of the asset related to the event.

• An overview of changed metadata, containing a list of metadata fields. This list contains the following:
• The old value before the asset was changed.
• The new, current value of the field.

A Webhook call for an asset_rename event may look as follows:

POST / HTTP/1.1 200
 
accept: 'text/plain, application/json, application/*+json, */*',
x-hook-signature: '7075ee512facd53294f4f50238019aa96bb1aafcbe3bea309ed78b7f9dafc4d4',
content-type: 'application/json',
content-length: '519',
host: 'localhost:4567',
connection: 'Keep-Alive',
user-agent: 'Apache-HttpAsyncClient/4.1.2 (Java/1.8.0_101)'
 
{
  "timestamp": 1478255419854,
  "type": "asset_rename",
  "assetId": "ABHCHae34sfB2ABO1O_4Ku",
  "metadata" : [
      "filename" : "someFile.png",
      "folderPath" : "User Zone/some/folder"
  ],
  "changedMetadata": {
    "status": {
      "oldValue": "New",
      "newValue": "Production",
    },
    "assetModified": {
      "oldValue": 1478255409015,
      "newValue": 1478255419760,
    }
  }
}  

Folder events

Event payloads related to folders contain the following information:

• The path to the folder related to the event.

A Webhook call for a folder_create event may look as follows:

POST / HTTP/1.1 200
accept: 'text/plain, application/json, application/*+json, */*',
x-hook-signature: '974fe14d36a4722c0f2bd3de75694b626ac9617148643301fd178abe439089bf',
content-type: 'application/json',
content-length: '87',
host: 'localhost:4567',
connection: 'Keep-Alive',
user-agent: 'Apache-HttpAsyncClient/4.1.2 (Java/1.8.0_101)'
{
 "timestamp": 1478256012358,
 "type": "folder_create",
 "folderPath": "/Demo Zone/SomeFolder"
}

Share Link events

Event payloads related to Share Links contain the following information:

• The authKey containing the unique ID that links to the Share Link.

• The subject of the Share Link.

• A description.

• Two timestamps that contain the creation and expiration times of the Share Link.

• The user name and full name of the creator.

• An e-mail which is used to notify about activity in the Share Link.

• Booleans defining specific configuration for:
• Approving requests
• Requesting uploads
• Allowing previews
• Allowing downloads
• Watermarks

A Webhook call for an authkey_create event may look as follows:

POST / HTTP/1.1 200
 
accept: 'text/plain, application/json, application/*+json, */*',
x-hook-signature: 'e6d534f491bd8ddfa3b330478c93ccc0275411eaa178e87606c3c38bc0b56daa',
content-type: 'application/json',
content-length: '371',
host: 'localhost:4567',
connection: 'Keep-Alive',
user-agent: 'Apache-HttpAsyncClient/4.1.2 (Java/1.8.0_101)'
 
{
  "timestamp": 1478256383411,
  "type": "authkey_create",
  "authKey": "kZOYhlI",
  "subject": "A share link",
  "description": "Some description",
  "validFrom": 1478256383397,
  "validUntil": 1480848364147,
  "creator": "admin",
  "creatorName": "admin",
  "notifyEmail": "email@example.com",
  "requestApproval": false,
  "requestUpload": false,
  "allowPreview": true,
  "allowDownload": true,
  "watermarked": false,
}