Working with Webhooks in Assets Server

A Webhook is a small piece of code attached to a Web application that listens for specific triggers and then performs a predetermined action. Webhooks make it possible to automate processes that previously had to be scheduled.

In Assets Server, Webhooks can be used to notify your application when certain events occur in Assets Server.

Example: You might want to alert and respond in your remote application when asset metadata is updated or when a Share Link is created.

When a defined event occurs, a HTTP POST with the event payload is sent to the URL that is configured in the Webhook.

Subscribing to events using a Webhook means that your application does not have to periodically poll Assets Server (via the REST APIs or through a Scheduled Plug-in) to determine whether changes have occurred.

This article describes how to work with Webhooks in Assets Server in the following ways:

• Registering a Webhook
• Updating a Webhook
• Generating a new secret token
• Disabling a Webhook
• Unregistering a Webhook
• Querying Webhooks
• Receiving and responding to payloads
• Defining the number of attempts before a Webhook is marked as failed

Additional information is available in the following articles:

• Assets Server API - Managing Webhooks
• Overview of the Webhook structure, its events and payloads
• Securing Webhooks

Requirements

Managing Webhooks requires the following:

• For Assets Server 6.49 and higher:
• A user with the role of 'Super user' in combination with a Pro license or an API license.

• For Assets Server 6.48:
• A user with the role of 'Super user' in combination with a Pro license.

Managing Webhooks

Managing Webhooks is done on the Webhooks page in the Management Console of Assets Server.

Step 1. Log in to Assets, click your Avatar and choose Management console from the menu.

Step 2. From the menu on the left of the page, choose Webhooks.

Registering a Webhook

To use a Webhook in Assets Server, it needs to be registered. This can be done by using the Management Console or through the Assets Server REST API.

Using the Management Console

Step 1. In the Management Console, access the Webhooks page:

Step 2. Add a new Webhook by clicking the +-sign.

Step 3. In the form that appears, enter all details for the Webhook.

Step 4. Click Save.

Using the Assets Server REST API

Note: For more detailed information including examples, see Assets Server API - Managing Webhooks.

POST a JSON object to the following URL:

<Assets Server_URL>/services/admin/webhook

The JSON object must contain the following fields:

• The name of the Webhook
• The callback URL of the Webhook
• A list of supported event types

Optionally, the JSON object may contain a list of metadata to return.

The response will contain the full Webhook object in JSON format.

Updating a Webhook

Updating a Webhook can be done by using the Management Console or through the Assets Server REST API.

Using the Management Console

Step 1. In the Management Console, access the Webhooks page:

Step 2. In the list of Webhooks, select the one you want to update.

Step 3. Edit the details and when done click Save.

Using the Assets Server REST API

Note: For more detailed information including examples, see Assets Server API - Managing Webhooks.

Step 1. Create a JSON object that contains the fields you wish to update and their new values.

Step 2. POST that JSON object to the following URL:

<Assets Server_URL>/services/admin/webhook/<WEBHOOK_ID>

The response will contain the updated Webhook object.

Generating a new secret token

Generating a new secret token can be done by using the Management Console or through the Assets Server REST API.

Using the Management Console

Step 1. In the Management Console, access the Webhooks page:

Step 2. In the list of Webhooks, select the one for which you want to generate a new secret token.

Step 3. Click Regenerate.

The new secret token will be displayed.

Using the Assets Server REST API

Note: For more detailed information including examples, see Assets Server API - Managing Webhooks.

POST a JSON object to the following URL:

<Assets Server_URL>/services/admin/webhook/<WEBHOOK_ID>generate-token

The response will contain the new secret token.

Disabling a Webhook

Info: This feature requires Assets Server 6.86 or higher.

When a Webhook is temporarily not needed or should temporarily not be running (for example during a period in which maintenance is performed), the Webhook can be disabled.

Webhooks for which too many failures within a 10-second time frame exist can be disabled automatically.

When the Webhook is disabled, no requests will be sent towards the endpoint until the Webhook is enabled again.

Disabled Webhooks are clearly indicated as such in the Management Console by a banner at the top of their page, and by a label in the list of Webhooks.

Enabling a Webhook again can be done by clicking the Enable button.

Manually disabling a Webhook

Step 1. In the Management Console, access the Webhooks page.

Step 2. In the list of Webhooks, select the one you want to disable.

Step 3. Click Disable.

Automatically disabling a Webhook

Webhooks for which too many failures within a 10-second time frame exist can be automatically disabled by setting the following option either on the Cluster properties page of the Management Console, or directly in the cluster-properties.txt file:

webHooksFailuresBeforeDisable

Set the option to -1 to never disable Webhooks on failures:

webHooksFailuresBeforeDisable=-1

Unregistering a Webhook

Unregistering a Webhook can be done by using the Management Console or through the Assets Server REST API

Using the Management Console

Step 1. In the Management Console, access the Webhooks page.

Step 2. In the list of Webhooks, select the one you want to unregister.

Step 3. Click Remove Webhook and confirm that you want to perform that action.

Using the Assets Server REST API

Note: For more detailed information including examples, see Assets Server API - Managing Webhooks.

Execute a DELETE to the following URL:

<Assets Server_URL>/services/admin/webhook/<WEBHOOK_ID>

When successful, Assets Server will send an empty-bodied response with a 'No content' status.

Querying Webhooks

To query all Webhooks, perform a GET with the following URL:

<Assets Server_URL>/services/admin/webhook

To get a specific Webhook by its ID, perform a GET with the following URL:

<Assets Server_URL>/services/admin/webhook/<WEBHOOK_ID>

Receiving and responding to payloads

Webhook payloads are sent over by HTTP. In order to receive them, a Web server needs to be set up which can be reached by your Assets Server.

After configuring your Webhook in Assets Server with the URL to the Web server, Assets Server will start sending payloads to that Web server.

Status codes

On normal Webhook calls, Assets Server expects to receive a response with a status code in the 2xx-range.

When Assets Server receives a response status code in the 5xx-range, the Webhook call will be retried a maximum of 8 times with increasing delay or until a successful response has been received.

If Assets Server receives status code in the 4xx-range, it will not retry the call and instead report the response body as a warning log.

Sample

For a sample of a Web server in NodeJS which is set up to receive Webhook payloads from Assets Server, see our Assets Server Simple Webhooks Sample on GitHub.

Defining the number of attempts before a Webhook is marked as failed

Info: This feature requires Assets Server 6.86 or higher.

To prevent a Webhook from endlessly re-running, the maximum number of retry attempts can be defined by setting the following option either on the Cluster properties page of the Management Console, or directly in the cluster-properties.txt file:

webHooksRetryMaximumAttempts=3