WoodWing Help Center

Overview of a Webhook and its payloads and events in Elvis 5

Overview of a Webhook and its payloads and events in Elvis 5

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

Webhooks

A Webhook in Elvis 5 consists of the following information:

  • A unique ID.
  • The URL to which the event payload is sent.
  • A list of Event Types which defines the events the Webhook is subscribed to.
  • A boolean stating whether the Webhook is enabled. Disabled Webhooks do not receive updates.
  • A Secret Token generated by Elvis. This can be used to verify the integrity of messages on the receiving side of the Webhook. For more information, See Securing Webhooks in Elvis 5.
  • An optional list of metadata fields, which will be returned with every event payload.

Notes:

  • This is only available for asset and folder events; authkey events do not have metadata.
  • You must supply the technical name for the metadata fields.

A Webhook may look as follows:

 [
    {
        id: "2n-UzMFgate9nAwg8zLXCs",
        url: "http://localhost:8081/",
        eventTypes: [
            "asset_rename",
            "asset_update_metadata"
        ],
        metadataToReturn: [
            "filename",
            "status"
        ],
        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:

Name Description
asset_checkin Fired when an asset is checked in.
asset_checkout Fired when an asset is checked out.
asset_create Fired after the creation of an asset.
asset_create_by_copy Fired when an asset is copied.
asset_create_from_version Fired when a version is created.
asset_move Fired after an asset is moved.
asset_promote Fired when a version is promoted.
asset_remove Fired after an asset is removed.
asset_rename Fired after renaming an asset.
asset_undo_checkout Fired when the check-out of an asset is canceled.
asset_update_metadata Fired when the metadata of an asset is changed.
authkey_create Fired when a Share Link is created.
authkey_remove Fired when a Share Link has been removed.
folder_create Fired when a folder is created.
folder_remove Fired when a folder is removed.

IMPORTANT: Events are fired after the occurrence of an action. For example, the event for removing an asset will be fired after the asset has been removed.

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,
}
Was this article helpful?
0 out of 0 found this helpful / Created: / Updated:
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.