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 1a. Log in to the Elvis Pro client, click your Avatar and choose Management console from the menu.
Step 1b. From the menu on the left of the page, choose Webhooks.
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 1a. Log in to the Elvis Pro client, click your Avatar and choose Management console from the menu.
Step 1b. From the menu on the left of the page, choose Webhooks.
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 1a. Log in to the Elvis Pro client, click your Avatar and choose Management console from the menu.
Step 1b. From the menu on the left of the page, choose Webhooks.
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 1a. Log in to the Elvis Pro client, click your Avatar and choose Management console from the menu.
Step 1b. From the menu on the left of the page, choose Webhooks.
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.
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.