Understanding Webhooks and vRx

Use webhooks to further automate your security posture

Prerequisites

Because we will be working with and understanding webhooks we will need a few tools. 

1. A basic understanding of Webhooks. Refer to this article to setup webhooks in vRx
2. You will need to set up an API key within vRx. Please take a look at this article for instructions on configuring an API key. 
3. Install postman or another API or any other RESTapi tool.
4. Configure Postman to use your API Key. Refer to this article for instructions. 
5. Configure a webhook listener. If you do not have one webhook.site will work. 

How it works

vRx can send webhooks when specific events happen. These events include when tasks are complete or when an incidentevent takes place (Detected Vulnerability or Removed Endpoint, etc.). 

1. A new CVE is released - vRx Detects a vulnerability in your environment. 
2. vRx logs this detection as an event
3. A "incidentEventIncidentEventType": "DetectedVulnerability" event is sent to all configured webhooks, including all the event details. The data is delivered in JSON format. 

Getting the data you want out of the webhook. 

Many Webhook listeners and automation platforms require that you provide sample data or send a webhook to be able to filter for the data you want. There are a few ways the data can be sent so the automation can be configured:

1. Perform the task or action in vRx
   While this option is easiest, it is only sometimes practical. 
   • This is the easiest method though it can take longer 
   • Once you have configured the webhook, Perform the action in vRx for which you want the webhook data. 
   • For example, If you would like to receive an email alert when a task completes with a status failed, Run an auto-action task and wait for the task to finish. When the task completes, you will receive a webhook and be able to filter by the Action Status. 
2. Query the API for the data, then send it to the webhook as a sample.
   This option requires a bit of work to accomplish but ultimately can be faster than waiting for a specific set of events to happen. 
   • Once you have configured the webhook, query the API, clean up the data, then send it to the webhook
   • For example, If you want to receive alerts based on detected vulnerabilities, You will query the API using an API tool like postman. Remove the serverObject headers from the body, then post the results to the webhook using postman. 

Basic Webhook Tutorial 

1. Refer to this article for a Basic webhook Guide

Advanced Webhook tutorial

1.  Follow the steps in the Basic webhook tutorial to configure the webhook 
2. Setup Postman to query the API 
3. In this example, we will query the  Incident Event Controller 
4. Create a new Get request in Postman 
5. Set the URL to https://<your-dashboard>.vicarius.cloud/vicarius-external-data-api/incidentEvent/filter?from=0&size=1
   1. 
6. Send the API Get request
7. Copy the result to a text editor like notepad
8. Delete the opening {, the ServerResponseResult, and the beginning of the ServerResponseObject 
   1. 
   2. It will look like this when you have deleted the right section
   3. 
9. Delete the closing } and ] from the end of the file 
   1. 
   2. It will look like this when you have deleted the right section
   3. 
10. Copy the JSON text
11. Go back to postman, Create a new post request
12. Enter the webhook URL in the post request and paste the modified JSON text in the body 
13. Send the request 
    1. 
14.  You will see the JSON data in the webhook listener