This article describes the various methods of using the Webhooks API.
For more information, see Working with Webhooks in Assets Server.
Registering a new Webhook
POST http://yourserver.com/services/admin/webhook |
What does it do?
Create a new Webhook.
Path Variables
None.
Request body
To register the Webhook, a JSON body containing the following parameters is required:
Name | Type | Description |
---|---|---|
name | String | Name of the Webhook. |
url | String | URL containing the location of the Webhook. |
eventTypes | String array | A list containing one or more types of events that should be posted to the Webhook. This list may be empty, but not null. |
metadataToReturn | String array | Optional. List of metadata fields which are returned for every event. |
triggerMetadataFields | String array |
An array of metadata field names. The Webhook will only trigger for assets of which at least one of the defined metadata fields has changed. Example: Optional and applies only to asset events. |
foldersAndQuery | Object |
A list of folders and queries. The Webhook will only trigger for assets that are located in the specified paths and meet the criteria of the query. Example: Optional and applies only to asset events. |
Return value
If successful, a JSON object containing the following fields will be returned:
Name | Type | Description |
---|---|---|
name | String | Name of the Webhook. |
id | String | Assets Server-generated ID for the Webhook. |
url | String | Location of the Webhook. |
eventTypes | String array | List of types of events the Webhook receives. |
metadataToReturn | String array | List of metadata fields which are returned for every event. |
enabled | boolean | (Default: true) Boolean stating whether the Webhook is enabled. |
secretToken | String | Randomly generated AES key that is used for verifying the origin of Webhook calls. |
triggerMetadataFields | String array |
List of metadata field names of which the values were changed which triggered the firing of the Webhook. Optional and applies only to asset events. |
foldersAndQuery | Object |
List of folders in which the targeted assets are located, and queries which criteria were met by the targeted assets. Optional and applies only to asset events. |
Examples
Successful call
- Create new Webhook
POST http://yourserver.com/services/admin/webhook
Content: {
"name" : "My Webhook",
"url" : "http://locationofa.webhook.com/some/path",
"eventTypes" : ["asset_rename", "asset_update_metadata"]
}
Returns the following response:
Status Code: 201 Created
Content: {
"id": "C__FNux9av_BIfk3VDyuO8",
"name" : "My Webhook",
"url": "http://locationofa.webhook.com/some/path",
"eventTypes": [
"asset_update_metadata",
"asset_rename"
],
"enabled": true,
"secretToken": "WMh2H3+53FHkQMNpRMwetw=="
}
Erroneous calls
- Supplying an invalid URL
POST http://yourserver.com/services/admin/webhook
Content: {
"name" : "My Webhook",
"url" : "bogus_url",
"eventTypes" : ["asset_rename", "asset_update_metadata"]
}
Returns the following error:
Status code: 200 OK
Content: {
"errorname": "MethodArgumentNotValidException",
"message": "Must be a valid URL",
"errorcode": 500
}
- Not supplying a field (eventTypes in this case)
POST http://yourserver.com/services/admin/webhook
Content: {
"name" : "My Webhook",
"url" : "http://locationofa.webhook.com/some/path"
}
Returns the following error:
Status code: 200 OK
Content: {
"errorname": "MethodArgumentNotValidException",
"message": "May not be null",
"errorcode": 500
}
Call including a filter
Note: The use of wildcards is not supported.
Content: {
id: "BBbN0ldca-oB2WWpI7Plcd"
name: "My Webhook"
url: "https://locationofa.webhook.com/some/path"
eventTypes: ["asset_create", "asset_update"]
metadataToReturn: ["assetDomain", "filename", "fileCreated", "approvalState", "assetType"]
triggerMetadataFields: ["filename"]
foldersAndQuery: {folders: ["nature"], query: "filename:flower"}
enabled: true
secretToken: "ZO6RCFXBGFFMhL6SI/TE3A=="
}
Updating a Webhook
PUT http://yourserver.com/services/admin/webhook/:id |
What does it do?
Update the fields of a Webhook.
Path variables
None.
Request body
Provide the parameters of the Webhook that need to be updated.
Name | Type | Description |
---|---|---|
name | String | Name of the Webhook. |
url | String | URL containing the location of the Webhook. |
eventTypes | String array | A list containing one or more types of events that should be posted to the Webhook. This list may be empty, but not null. |
metadataToReturn | String array | Optional. List of metadata fields which are returned for every event. |
enabled | boolean | Optional: Set Webhook enabled or disabled. |
triggerMetadataFields | String array |
An array of metadata field names. The Webhook will only trigger for assets of which at least one of the defined metadata fields has changed. Example: Optional and applies only to asset events. |
foldersAndQuery | Object |
A list of folders and queries. The Webhook will only trigger for assets that are located in the specified paths and meet the criteria of the query. Example: Optional and applies only to asset events. |
Note: Parameters that are left null will not be updated.
Return value
If successful, the updated Webhook object will be returned, containing the following fields:
Name | Type | Description |
---|---|---|
name | String | Name of the Webhook. |
id | String | ID of the Webhook. |
url | String | Location of the Webhook. |
eventTypes | String array | List of types of events the Webhook receives. |
metadataToReturn | String array | List of metadata fields which are returned for every event. |
enabled | boolean | Boolean stating whether the Webhook is enabled. |
secretToken | String | Randomly generated AES key that is used for verifying the origin of Webhook calls. |
triggerMetadataFields | String array |
List of metadata field names of which the values were changed which triggered the firing of the Webhook. Optional and applies only to asset events. |
foldersAndQuery | Object |
List of folders in which the targeted assets are located, and queries which criteria were met by the targeted assets. Optional and applies only to asset events. |
Examples
Successful calls
- Update URL and Event Types of a Webhook
PUT http://yourserver.com/services/admin/webhook/C__FNux9av_BIfk3VDyuO8
Content: {
"url" : "http://locationofa.webhook.com/some/new/path",
"eventTypes" : ["asset_create"]
}
Returns the following response:
Status Code: 200 OK
Content: {
"id": "C__FNux9av_BIfk3VDyuO8",
"name": "My Webhook",
"url": "http://locationofa.webhook.com/some/new/path",
"eventTypes": [
"asset_create"
],
"metadataToReturn": [
"status"
],
"enabled": true,
"secretToken": "WMh2H3+53FHkQMNpRMwetw=="
}
- Disabling a Webhook
PUT http://yourserver.com/services/admin/webhook/C__FNux9av_BIfk3VDyuO8
Content: {
"enabled": false,
}
Returns the following response:
Status Code: 200 OK
Content: {
"id": "C__FNux9av_BIfk3VDyuO8",
"name": "My Webhook",
"url": "http://locationofa.webhook.com/some/path",
"eventTypes": [
"asset_checkin",
"asset_checkout",
"asset_undo_checkout"
],
"metadataToReturn": [
"status"
],
"enabled": false,
"secretToken": "WMh2H3+53FHkQMNpRMwetw=="
}
Erroneous calls
- Invalid event types
PUT http://yourserver.com/services/admin/webhook/C__FNux9av_BIfk3VDyuO8
Content: {
"eventTypes" : ["bogus_event"]
}
Returns the following response:
Status code: 200 OK
Content: {
"errorname": "MethodArgumentNotValidException",
"message": "Invalid Event Types found.",
"errorcode": 400
}
- Webhook with provided ID does not exist.
PUT http://yourserver.com/services/admin/webhook/bogus_id
Returns the following response:
Status code: 404 Not Found
Content: "Webhook not found."
Generating a new secret token for a Webhook
PUT http://yourserver.com/services/admin/webhook/:id/generate-token |
What does it do?
Generate a new secret token for a Webhook.
Path variables
id | ID of the Webhook to generate a new secret token for. |
Parameters
None.
Return value
A String containing the new secret token.
Examples
Successful call
- Update Event Types of a Webhook
PUT http://yourserver.com/services/admin/webhook/C__FNux9av_BIfk3VDyuO8/generate-token
Returns the following response:
Status Code: 200 OK
Content: {
"secretToken" : "WMh2H3+53FHkQMNpRMwetw=="
}
- Webhook with provided ID does not exist.
PUT http://yourserver.com/services/admin/webhook/bogus_id/generate-token
Returns the following response:
Status code: 404 Not Found
Content: "Webhook not found."
Deleting a Webhook
DELETE http://yourserver.com/services/admin/webhook/:id |
What does it do?
Delete a Webhook.
Path variables
id | ID of the Webhook to delete. |
Note: For testing purposes, you can provide “all” instead of the ID to quickly delete all registered Webhooks.
Parameters
None.
Return value
Returns a 204 No Content
message when the Webhook has been successfully deleted or a 404 Not Found
error when a non-existing or invalid ID was supplied.
Examples
Successful call
- Delete a Webhook
DELETE http://yourserver.com/services/admin/webhook/C__FNux9av_BIfk3VDyuO8
Returns the following response:
Status code: 204 No Content
Erroneous call
- Webhook with provided ID does not exist.
GET http://yourserver.com/services/admin/webhook/bogus_id
Returns the following response:
Status code: 404 Not Found
Content: "Webhook not found."
Querying all Webhooks
GET http://yourserver.com/services/admin/webhook |
What does it do?
Returns a list of all registered Webhooks.
Parameters
None.
Return value
A JSON object containing a list of Webhook objects or an empty list when no Webhooks exist.
A single Webhook object contains the following data:
Name | Type | Description |
---|---|---|
name | String | Name of the Webhook. |
id | String | ID of the Webhook. |
url | String | Location of the Webhook. |
eventTypes | String array | List of types of events the Webhook receives. |
enabled | boolean | Boolean stating whether the Webhook is enabled. Disabled Webhooks do not receive updates. |
secretToken | String | Randomly generated AES key that is used for verifying the origin of Webhook calls. |
triggerMetadataFields | String array |
An array of metadata field names. The Webhook will only trigger for assets of which at least one of the defined metadata fields has changed. Example: Optional and applies only to asset events. |
foldersAndQuery | Object |
List of folders in which the targeted assets are located, and queries which criteria were met by the targeted assets. Optional and applies only to asset events. |
Examples
Successful call
- Show all Webhooks
GET http://yourserver.com/services/admin/webhook
Returns the following response:
Status code: 200 OK
Content: [
{
id: "C__FNux9av_BIfk3VDyuO8",
"name" : "My Webhook",
url: "http://locationofa.webhook.com/some/path",
eventTypes:
[
"asset_update_metadata",
"asset_rename"
],
enabled: true,
secretToken: "kwQMEL5dGdyey7Cdzo4PYQ=="
},
{
id: "0ldCt5DBKpw94GG3EcTT_N",
"name" : "My other Webhook",
url: "http://locationofa.webhook.com/some/other/path",
eventTypes:
[
"asset_checkout",
"asset_checkin",
"asset_undo_checkout"
],
enabled: false,
secretToken: "WMh2H3+53FHkQMNpRMwetw=="
}
]
Erroneous call
- Not logged in
GET http://yourserver.com/services/admin/webhook
Returns the following response:
Status code: 200 OK
Content: {
"errorname": "UNAUTHORIZED",
"message": "Not logged in",
"errorcode": 401
}
Querying Webhooks by ID
GET http://yourserver.com/services/admin/webhook/:id |
What does it do?
Returns a single Webhook.
Path variables
id | ID of the Webhook to return. |
Parameters
None.
Return value
A JSON object containing the Webhook. If a Webhook with the provided ID does not exist, a “Not Found” response containing “Webhook not found.” will be returned.
A Webhook object contains the following data:
Name | Type | Description |
---|---|---|
name | String | Name of the Webhook. |
id | String | ID of the Webhook. |
url | String | Location of the Webhook. |
eventTypes | String array | List of types of events the Webhook receives. |
metadataToReturn | String array | List of metadata fields which are returned for every event. |
enabled | boolean | Boolean stating whether the Webhook is enabled. |
secretToken | String | Randomly generated AES key that is used for verifying the origin of Webhook calls. |
triggerMetadataFields | String array |
An array of metadata field names. The Webhook will only trigger for assets of which at least one of the defined metadata fields has changed. Example: Optional and applies only to asset events. |
foldersAndQuery | Object |
List of folders in which the targeted assets are located, and queries which criteria were met by the targeted assets. Optional and applies only to asset events. |
Examples
Successful call
- Show gingle Webhook
GET http://yourserver.com/services/admin/webhook/C__FNux9av_BIfk3VDyuO8
Returns the following response:
Status code: 200 OK
Content: {
id: "C__FNux9av_BIfk3VDyuO8",
"name": "My Webhook",
url: "http://locationofa.webhook.com/some/path",
eventTypes:
[
"asset_update_metadata",
"asset_rename"
],
enabled: true,
secretToken: "kwQMEL5dGdyey7Cdzo4PYQ=="
}
Erroneous calls
- Webhook with provided ID does not exist.
GET http://yourserver.com/services/admin/webhook/bogus_id
Returns the following response:
Status code: 404 Not Found Content: "Webhook not found."
- Not logged in
GET http://yourserver.com/services/admin/webhook/C__FNux9av_BIfk3VDyuO8
Returns the following response:
Status code: 200 OK
Content: {
"errorname": "UNAUTHORIZED",
"message": "Not logged in",
"errorcode": 401
}
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.