PDF version: WebhooksSummary.pdf

OVERVIEW:

Webhooks enable users to collect events using a public endpoint where they are able to push the events through authenticated HTTP requests.

When a user creates a webhook connector and provides the name and plugin, USMA provides an API Key and an endpoint. With the webhook API, users will be able to code an integration between USMA and a third-party tool. This integration will inject events into USMA. These events will be tagged with the correct data source which the user can select from the system list or a new one that is created by the user who created the webhook connector.

The advantage of a webhook is that it sends data in real-time, whenever an event happens. Another advantage of a webhook is that it doesn’t involve communication when no relevant events have occurred. Webhooks require setting up a POST request and endpoint in a system that is going to send the data, and the system receiving the data must have a URL to send the data to.

NOTE: While creating a webhook connector, if no plugin data source is provided, then the plugin will be either “auto-discovered data source” or the events pushed will be considered “generic”.

MANAGING WEBHOOKS

In USMA, you can create more than one webhook and use them for different purposes. For example, you can create multiple webhooks to push events from different data sources to USMA.

You can also edit or delete the webhooks that have been created.

CREATING A NEW WEBHOOK:

Step 1: Navigate to DATA SOURCES and click on Cloud Connectors

Step 2: Click on Add Connector on the top right corner

Step 3: Select connector type as “Webhook” from the dropdown

Step 4: Select Data Source from the dropdown

(This selection is optional, if not selected it will either auto-discover or consider the event as Generic)
Note: Data Source can be a custom app previously created.

Step 5: Name your connector as you want it to be and click on next as shown below.

(You cannot create any duplicate webhook with same name and data source that already exists)

(Names support underscore and hyphen)

Step 6: Success message will be displayed and API KEY and Webhook URL will be revealed as shown below.

Step 7: Copy the API KEY and Webhook URL and store these credentials in a text file

Step 8: The created webhook appears in the list of connectors

EDITING AN EXISTING WEBHOOK:

Step 1: Navigate to DATA SOURCES and click on Cloud Connectors

Step 2: Click on the ellipsis available on the right side of the webhook you want to edit

Step 3: Click on Edit

Step 3: Now you can change your webhook name or data source

Note: you cannot duplicate any other webhook that already exists

Step 4: Click on Save

DELETING AN EXISTING WEBHOOK:

Step 1: Navigate to DATA SOURCES and click on Cloud Connectors

Step 2: Click on the ellipsis available on the right side of the connector you want to delete

Step 3: Click on Delete

Step 4: Click on Delete when the popup confirmation appears

RESET API KEY:

Step 1: Navigate to DATA SOURCES and click on Cloud Connectors

Step 2: Click on the ellipsis available on the right side of the connector you want to reset the API KEY

Step 3: Click on Reset API Key

Step 4: Click on Reset when the popup confirmation appears

Step 5: Now the API KEY along with Webhook name will be reset and displayed

Step 6: Copy and save the API Key in a secure place and close the popup

PUSHING EVENTS

After the webhook is configured, you can use it to push events to USMA.

Step 1: Open postman and paste the Webhook URL you have saved while creating a webhook

Step 2: Add a header with key “API_KEY” and value <paste the API KEY you saved while creating or resetting a webhook>

Step 3: Make sure this is a “post request”

Step 4: Add the events in the body section

Step 6: You will see a success message that your events have been pushed

Step 7: Open the events page in USMA and confirm the collected events have been pushed.

PUSHING SINGLE EVENT:

Below is the curl command and a sample screenshot to push a single event:

PUSHING MULTIPLE EVENTS:

A maximum of 50 simultaneous events can be pushed in json format.

Below is the curl command and a sample screenshot to push multiple events:

ERRORS:

400 Bad Request:

When you try to push events without providing the events in body section, you will get “400 Bad Request” as shown below

404 Not Found:

When you try to push events without providing the correct ApiKey, you will get “404 Not Found” as shown below.

STATUS:

When a new webhook is created, it will be added to the cloud connectors list and the status will be “Offline”.

Once you push any events utilizing this webhook API, the status will change to “Active”.

If no data has been received for the past 12 hours, the status changes to “Idle” and if no data has been received for the past 24 hours, the status will be changed to “Not Receiving Data”.

WEBHOOK STATUS:

Connector stats will be displayed by 1-hour increments when the user clicks on “24 hours” as shown in the image below:

Connector stats will be displayed in 24-hour increments when the user clicks on “7 Days” as shown in the image below: