Webhooks Feature Quick Start Guide


Document Version History

Version number

Modified by

Modifications made

Date modified

Status

1.0

Shelf

Initial release of the Shelf Webhooks Feature Quick Start Guide. 

06 April 2022

Active





















Introduction

This document is designed for administrators of Shelf’s clients who need to keep track of how users within their organizations interact with the Shelf platform.



Webhooks, Their Purpose and Benefits

What is a webhook and how can it be used?

Webhooks as implemented in the Shelf platform are automated messages that are generated and sent by Shelf upon certain events. To some extent, a webhook works as a push notification sent to a client-specified recipient. This recipient can be an external application, a file, a database, or even a server.

A standard webhook contains a message—also known as “payload”—and is sent by the system to a predefined unique URL address.


Example of a webhook sent to a recipient


JSON representation

{
"payload": {
"accountId": "eb1541e7-ce1a-4d76-865d-f184468b3544",
"action": "USER.SIGN_OUT",
"actorUser": {
"email": "jdoe@mail.com",
"fullName": "John Doe",
"id": "9d0939cb-47fa-4285-96ae-ab3dccc90dcb"
},
"createdAt": "2022-04-05T14:53:00.358Z",
"id": "01FZX3DXJ6HJXXQN7ZKMB8MRPN"
}
}
Webhooks work much faster as compared to the application polling. Moreover, using webhooks requires much less effort from the user side.
The practical use of Shelf webhooks is that you can use them to subscribe to various events generated when a Shelf user is created or deleted, or when a user logs in to or out of Shelf. One of the most common use cases of data received from such subscriptions is feeding them into your Security Information and Event Management (SIEM) applications for analysis or any other purpose.


Difference between an API and a webhook

Any webhook you create and configure for your business purposes is an event-based entity. It means that this webhook is expected to run when a specific event occurs in the respective source application.

The key difference between APIs and Webhooks is that for a webhook to provide a response you do not need to send a request. At the same time, you ALWAYS need to send a request to an API in order to get a response.

In short, you receive data via webhooks and you retrieve data via APIs.



Prerequisites

In order to enjoy the full use of the Shelf Webhooks feature, the following preconditions must be met.

  1. Ensure that the Audit Log feature is included in your subscription plan. For this purpose, contact your Shelf representative and verify it is in your plan. If it is not, it can be ordered and enabled at an additional cost.
  2. Make sure your user has the Admin level of permissions. For this purpose, when on the main page of the Shelf platform, navigate to your user logo and open the dropdown menu. Then select the Admin Panel option to bring the Admin Panel to the screen. If you are able to get to the Admin Panel, it means your user has the Admin permissions.

Figure 1. Accessing the Admin Panel

3. Verify that the Audit Log option is enabled in the Customize submenu. For this purpose, in the Admin Panel, locate and select the Customize submenu to open advanced customization options. Then, under the Features tab, locate and enable the Audit Log option by turning the respective toggle on.

Figure 2: Enabling the Audit Log option

4. Take care of the relevant server and endpoint setup and preconfiguration. They are needed to properly receive messages from Shelf’s API. It is your responsibility to select a suitable server.

If all the above preconditions are met, you can now start working with Shelf’s Webhooks feature. Jump to the below sections to find out which actions you can do on webhooks.



Limitations

In addition to the prerequisites, an efficient use of the Shelf Webhooks feature has certain restrictions, which are as follows:

  • Not more than 5 (five) unique webhooks can be created from the Manage Webhooks submenu.
  • One webhook can contain no more than 7 (seven) internal Shelf events.
  • Your webhook endpoint is expected to respond with the HTTP status 2xx in 5 secondsor less. If the response is sent outside this timeframe, the webhook payload delivery is considered as failed. From our side, Shelf retries sending failed payloads for up to 3 times.


Create Webhooks

To start using the Webhooks feature of the Shelf platform, you first need to create a webhook.

☝ NOTE:
For user convenience reasons, we describe the webhook creation procedure on the example of the Shelf user logout. It means that the selected condition for the webhook to be triggered is user.sign_out. In general, the creation of webhooks that are to be triggered by other causes in the Shelf platform follows the same steps.

To create a new webhook, perform the following procedure.

  1. In the Admin Panel, locate and select the Manage Webhooks submenu.

Figure 3. Accessing the Webhooks feature

2. On the Manage Webhooks page that opens, find and click the ADD WEBHOOK button.

Figure 4. Starting to create a webhook

3. In the Add Webhook form that appears, fill in the required fields and select the required checkboxes in accordance with the figure and table below. In our case, we use the user.sign_out condition that will be also used for verification of the created webhook operation.

Figure 5. Creating a webhook

Table 1. Add Webhook form elements

Element name

Requirement

Details

Webhook name

Mandatory

Enter any desired name of the webhook; max length must not exceed 60 characters.

Status

Mandatory

This element has two states represented by the checkboxes:

  • Disabled: your webhook configuration is saved, but it’s not being triggered after creation.
  • Enabled: the webhook configuration is saved and it becomes triggered as soon as the new event arrives.

Endpoint URL

Mandatory

Enter an URL address of an endpoint to which Shelf is expected to send events in case new users are created in the system. The indicated endpoint URL must be capable of accepting POST HTTPS requests.

☝NOTE: For the purpose of future verification of the webhook operation, we use https://webhook.site as a service that helps check and verify webhooks. When you open this link in your browser, you are offered to copy the endpoint URL you can use for your webhook testing. In our case, this endpoint URL is https://webhook.site/4686d315-a53b-4838-b8dc-fafb73e286fb?. In a real-world scenario, use your the endpoint URL offered by your dedicated server. 

Description

Optional

In this text field, enter any description for your webhook. It should not exceed 500 characters.

Events to send

Required

This element is where you need to select from 1 to 7 types of conditions that are to generate events to be sent to the specified endpoint.

The available condition types are:

  • User.sign_in_success: An event is expected to be sent upon each successful user sign-in.
  • user.sign_in_failure: An event is expected to be sent upon each failed attempt of the user sign-in. The event also shows the reason for a failed sign-in, for example wrong password or too many sign-in attempts.
  • user.sign_out: An event is expected to be sent upon each successful user sign-out.
  • user.pwd_changed: An event is expected to be sent upon each successful change of a user password.
  • user.account_role_change: An event is expected to be sent each time the admin changes the user’s role in Shelf.
  • user.creation: An event is expected to be sent upon a successful creation of user profile in Shelf.
  • account.settings_update: An event is expected to be sent when the admin updates settings in the user account; currently, the event is triggered only when the admin enables or disables features on the account.

CANCEL

N/A

If you no longer need to create a webhook, click this button to stop the procedure and close the form without saving the changes made.

ADD

N/A

Click this button to finish the webhook creation procedure and save the new webhook.


4. Once you have filled in all the required fields, set the required condition(s), and confirmed it by clicking the ADD button, the new webhook is created and saved.

Figure 6. Viewing the created webhook



Verify the webhook operation

Let’s now verify the webhook operation by the example of the user sign-out event. This exemplary verification is needed to show that your managers are able to track activities of their agents.

☝NOTE:
Any of the conditions/events indicated in Table 1 can be used for verification of the webhook operation.

In order to check if the created webhook is triggered properly, that is the system creates and sends relevant events to your endpoint, you need to log out of your Shelf account


Log out of Shelf

To log out of your Shelf account, perform the following steps.

  1. When on the Shelf main page, find and click your user pic in the upper right corner of the window.
  2. In the dropdown menu that appears, select the Logout option.

Figure 7. Logging out of Shelf

Once you are logged out, you are redirected to the Shelf login screen.


Check the webhook event

To make sure that the webhook you have created generates and submits proper events to your endpoint, log in to your server (or database, if applicable) and check if the respective event has been added.

As mentioned in the Note in Table 1, in the course of our webhook creation, we used the endpoint URL generated by https://webhook.site. This service is also used here in this section to check where the webhook we have previously created triggers proper events. In our case, this event must be triggered by logging out of the Shelf account.

To check if the webhook has triggered and sent the respective event upon the user logout, open the above URL address and see if there is any new record. If there is a new record and if it is about a webhook-triggered event, it must look like this:

Figure 8. Verifying the webhook event receipt

From the figure above, it is obvious the webhook was created and it generated the proper event (“USER.SIGN_OUT”} on the specified date and at the specified time (“2022-04-05T14:53:00.358Z”) as a result of the user that was registered under the specified email address (“jdoe@mail.com”) logging out of Shelf.

All this proves that the Shelf Webhook feature works as expected and triggers the proper event as a result of a certain action, which in our case is user logout.


Manage Webhooks

In Shelf, in addition to creating webhooks, it is also possible to manage them. For instance, you can edit webhooks you have previously created, disable them, or even delete.

☝NOTE: 

In order to show a variety of conditions that trigger events in the Shelf Webhook feature, webhook editing, disabling, and deletion are described by the example of a new user creation webhook. You should note that any webhook you have previously created can be edited, disabled, and/or deleted.

Edit a webhook

In order to edit the existing webhook, follow the below procedure.

  1. Go to the MANAGE WEBHOOKS page by selecting the Manage Webhooks submenu in the Admin Panel. On this page, you can open the webhook that you want to edit either by directly clicking it or by opening the Actions menu and selecting the Open option.

Figure 9. Opening a webhook

2. Once you get to the EDIT WEBHOOK form, you can edit any data you have entered for this webhook at its creation. For more details on the form fields and elements, refer to Table 1 above.

Figure 10. Editing a webhook

3. Once done with the editing, you can either click SAVE to save the changes made and update the webhook or click CANCEL to disregard the changes and close the form. In the latter case, the pop-up window appears with the respective warning. If you still want to delete the changes, confirm your choice by clicking LEAVE THIS PAGE. In that case, the pop-up window closes and the changes made are deleted, and you are redirected to the MANAGE WEBHOOKS page. Otherwise, you can click STAY ON THIS PAGE, which closes the pop-up window and redirects you to the EDIT WEBHOOK form where you can continue making the needed changes.

Figure 11. Warning message


               

Disable a webhook

At a certain point, any of the previously created webhooks can become unneeded for some time. In that case, you can temporarily disable this webhook. To do so, perform the following.

Go to the MANAGE WEBHOOKS page and perform one of the following actions:

  1. Open the Actions menu next to the needed webhook and select the Disable option from the list.

Then in the pop-up window that appears, confirm your choice by clicking DISABLE.

Figure 12. Warning message when disabling a webhook

2. On the MANAGE WEBHOOKS page, click the needed webhook to open its EDIT WEBHOOK form. Then in this form, change the webhook status to Disabled by selecting the respective checkbox.

Figure 13. Switching webhook status to Disabled

Once the Disabled checkbox is selected, click SAVE to confirm the end of editing.

Figure 14. Saving a disabled webhook

Then confirm your intention by clicking the SAVE button in the warning pop-up window as shown in Figure 11.

Regardless of the method you have chosen to disable the webhook, once the respective button (DISABLE or SAVE) is clicked, the webhook status changes to Disabled, and you can see it near to the respective webhook on the MANAGE WEBHOOKS page.

Figure 15. Viewing the webhook status


Delete a webhook

If you no longer need any of the previously created webhooks, you can easily delete them from Shelf. To do so, perform the following.

Go to the MANAGE WEBHOOKS page and perform one of the following actions:

  1. Open the Actions menu next to the needed webhook and select the Delete option from the list.

Figure 16. Delete option in the Actions menu

Then in the pop-up window that appears, confirm your choice by clicking DELETE.

Figure 17. Confirming webhook deletion

2. On the MANAGE WEBHOOKS page, click the needed webhook to open its EDIT WEBHOOK form. Then in this form, locate and click the DELETE button.

Figure 18. DELETE button in the EDIT WEBHOOK form

Then in the pop-up window that appears, confirm your choice by clicking DELETE as shown in Figure 17 above.

Regardless of the method you have chosen to delete the webhook, once the respective button (DELETE) is clicked, the webhook is removed.

Figure 19. Viewing available webhooks

If you have successfully completed the actions described in the sections above, it means that you now understand how the Shelf Webhooks feature works and how to create, edit, enable/disable, and delete webhooks.