Assets Server API - Managing Webhooks – Help Center

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: `triggerMetadataFields: ["filename", "status"]` 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: `{folders: ["/path/to/folder", "/another/folder"], query: "status:new OR status:draft"}` 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:`triggerMetadataFields: ["filename", "status"]` 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:`{folders: ["/path/to/folder", "/another/folder"], query: "status:new OR status:draft"}` 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: `triggerMetadataFields: ["filename", "status"]` 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: `triggerMetadataFields: ["filename", "status"]` 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
                 }

Registering a new Webhook

What does it do?

Path Variables

Request body

Return value

Examples

Successful call

Erroneous calls

Call including a filter

Updating a Webhook

What does it do?

Path variables

Request body

Return value

Examples

Successful calls

Erroneous calls

Generating a new secret token for a Webhook

What does it do?

Path variables

Parameters

Return value

Examples

Successful call

Deleting a Webhook

What does it do?

Path variables

Parameters

Return value

Examples

Successful call

Erroneous call

Querying all Webhooks

What does it do?

Parameters

Return value

Examples

Successful call

Erroneous call

Querying Webhooks by ID

What does it do?

Path variables

Parameters

Return value

Examples

Successful call

Erroneous calls

Related articles