Logo Help Center

Working with Webhooks in Elvis 6

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:

Additional information is available in the following articles:

Requirements

Managing Webhooks requires the following:

  • Managing through an API: an API license
  • Managing through Elvis Server: a user with the role of 'Super user'

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.

Creating a new Webhook

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 REST 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.

Editing a Webhook

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 REST 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.

Editing a Webhook

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 REST 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.

Editing a Webhook

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 REST 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.

Was this article helpful?
0 out of 0 found this helpful / Created: / Updated:
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.