Working with Webhooks in Elvis 6

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 allow you to automate processes that previously had to be scheduled.

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

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 Elvis (via the REST APIs or through a Scheduled Plug-in) to determine whether changes have occurred.

Tip: To learn more about Webhooks about what they can do for you when using Elvis, read our Blog post.

This article describes how to work with Webhooks in Elvis 6 in the following ways:

• Registering a Webhook
• Updating a Webhook
• Generating a new secret token
• Unregistering a Webhook
• Querying Webhooks
• Receiving and responding to payloads

Additional information is available in the following articles:

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

Requirements

Managing Webhooks requires a user with the role of 'Super user' in combination with a Pro license.

Registering a Webhook

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

Using the Management Console

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

Step 2. Click Add Webhook.

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

Step 4. Click Save.

Using the Elvis REST API

Note: For more detailed information including examples, see Elvis 6 API - Managing Webhooks.

POST a JSON object to the following URL:

<ELVIS_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 Elvis 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 Elvis REST API

Note: For more detailed information including examples, see Elvis 6 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:

<ELVIS_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 Elvis 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 Elvis REST API

Note: For more detailed information including examples, see Elvis 6 API - Managing Webhooks.

POST a JSON object to the following URL:

<ELVIS_URL>/services/admin/webhook/<WEBHOOK_ID>generate-token

The response will contain the new secret token.

Unregistering a Webhook

Unregistering a Webhook can be done by using the Management Console or through the Elvis 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 Elvis REST API

Note: For more detailed information including examples, see Elvis 6 API - Managing Webhooks.

Execute a DELETE to the following URL:

<ELVIS_URL>/services/admin/webhook/<WEBHOOK_ID>

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

Querying Webhooks

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

<ELVIS_URL>/services/admin/webhook

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

<ELVIS_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 Elvis server.

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

Status codes

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

When Elvis 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 Elvis 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 Elvis, see our Elvis Simple Webhooks Sample on GitHub.

Document history

• 18 June 2020: Updated section 'Requirements' by removing the reference that Webhooks can be managed through an API.