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.
Notes:
|
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:
Name | Description |
---|---|
asset_checkin | Fired when an asset is checked in. |
asset_checkout | Fired when an asset is checked out. |
asset_create |
|
asset_create_by_copy | Fired when an asset is copied. |
asset_create_from_filestore_rescue | Fired when an index entry is created as part of the Rescue tool. |
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:
|
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,
}
Comment
Do you have corrections or additional information about this article? Leave a comment! Do you have a question about what is described in this article? Please contact Support.
0 comments
Please sign in to leave a comment.