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:

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

2. Once a day, Oort will send an event to a webhook with a payload including the list of new users failing this check

3. 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:

1. Navigate to Integrations -> Add Integration -> Webhooks
2. Provide the following:

   1. Display name

   2. Description (optional)

   3. Webhook URL
3. Choose the appropriate Authorization Type for your webhook integration

   1. Basic - provide the Username and Password, as shown above

   2. API Key - provide the API key name and API key value
   3. OAuth Client Credentials

      1. Enter the Authorization endpoint URL

      2. Select HTTP method - POST, PUT, GET

      3. Enter Client ID and Client secret

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

4. Add any necessary Invocation HTTP Parameters - Invocation HTTP parameters are additional parameters that can be sent to a webhook and used during request authorization.

5. 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:

{
  "version": "0",
  "id": "abf0607d-3856-b397-5138-0131ec1b63d7",
  "detail-type": "WebhookTest",
  "source": "11111111-2222-3333-4444-555555555555__66666666",
  "account": "000000000000",
  "time": "2023-08-08T13:27:22Z",
  "region": "us-east-2",
  "resources": [],
  "detail": {
    "id": "11111111-2222-3333-4444-555555555555",
    "checkId": "oort-test-check-id",
    "title": "OORT Failing Check Event Test",
    "description": [
      "description1",
      "description2"
    ],
    "recommendedActions": [
      "action1",
      "action2"
    ],
    "severity": "critical",
    "usersFailing": [
      "[e-mail]",
      "[e-mail]"
    ],
    "published": "2023-08-08T13:27:22.416Z"
  }

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:

{
id: string; // event id
checkId: string; // check identifier
title: string;
description: string[];
recommendedActions: string[];
severity: string; // 'critical', 'moderate' or 'low'
usersFailing: string[]; // array of end user logins
published: string;
}

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