Webhooks
9/2023
Overview
In addition to notification destinations like Microsoft Teams, Slack channels, and email destinations, Oort supports webhooks as a target for Failed Check findings.
This article explains how to configure webhooks in Oort and provides several basic examples.
Requirements
The following is required to leverage webhooks with Oort -
Moderate familiarity with webhooks (external overview) as a method of platform-to-platform communication
A platform capable of receiving webhooks and ideally parsing a JSON payload for resulting categorization or desired action(s)
Design Considerations
To successfully leverage Oort webhooks, it is best to first fully conceptualize a desired outcome when a user object within the Oort platform is flagged for a particular Check.
A basic use case might be:
Configure a webhook destination to an automation platform, such as Okta Workflows or a SOAR solution and assign it to a particular Oort Check, such as No MFA
Once a day, Oort will send an event to a webhook with a payload including the list of new users failing this check
For each user account in the list, send an email from a specific company-specific email address with instructions for the user to enroll in MFA
The possibilities are endless and very specific to the context of the Oort Check upon which you want to take action.
API Authorization
One key design consideration is how the Oort webhook communication will authenticate and be authorized to the recipient platform. Oort supports the following methods:
Basic (username and password)
API Key
OAuth Client Credentials
Each of these types are explored in more detail in the examples below. The main determining factor here is the type(s) of authorization supported by the target platform.
Oort Configuration
To create a webhook notification integration, perform the following steps:
Provide the following:
Display name
Description (optional)
Choose the appropriate Authorization Type for your webhook integration
Basic - provide the Username and Password, as shown above
Enter the Authorization endpoint URL
Select HTTP method - POST, PUT, GET
Enter Client ID and Client secret
Add any necessary OAuth HTTP Parameters - OAuth HTTP parameters are additional credentials used to sign the request to the authorization endpoint to exchange the OAuth Client information for an access token.
Add any necessary Invocation HTTP Parameters - Invocation HTTP parameters are additional parameters that can be sent to a webhook and used during request authorization.
Click Save
Testing the Webhook Integration
On the main Integrations page, find the row under Notifications section corresponding to the Webhook notification target you just created.
Click the 3-dot menu on the righthand side and select Test Connectivity.
This will send a test message to the webhook destination. The contents of the message will be:
This is a basic message to confirm that connectivity is successful.
Enabling Webhook Notifications for Checks
When the webhook integration is created, it is not assigned to any check notifications by default. Nothing will be sent via the webhook until it is enabled in the desired Oort Check(s).
To enable it, navigate to the desired Check details page and expand the dropdown on the top-right corner of the page.
Check the box of the webhook that you would like enabled for this check.
Note that on the main Checks page, there is a Run Checks Now button in the top right corner. This will re-analyze the existing data set and any new Checks insights will trigger new notifications to any of the connected notification targets.
Oort Failed Check Notification Payload
The payload of an actual Check notification will be as follows:
In most cases, the receiving platform will need to do some level of parsing of this content, unless the intent is simply to store the information in a 3rd party SIEM or security data lake. (Note that Oort has direct integrations for Azure Sentinel or Snowflake security data lakes.)
Last updated