# Webhooks

## Overview

In addition to notification destinations like Microsoft Teams, Slack channels, and email destinations, CII supports webhooks as a target for Failed Check findings.  

This article explains how to configure webhooks in CII and provides several basic examples.

### Requirements

The following is required to leverage webhooks with CII -

* <mark style="color:red;">IMPORTANT</mark>:  The webhook destination, such as a SIEM like Splunk Enterprise Security, must have a valid public trusted certificate.  At this time, a certificate from a private PKI will not work.&#x20;
* If you are filtering inbound network traffic to the destination, please add the AWS IP ranges for your specific Duo-CII region (e.g. Europe) as outlined [here](https://docs.aws.amazon.com/vpc/latest/userguide/aws-ip-ranges.html).&#x20;
* Moderate familiarity with webhooks ([external overview](https://swimlane.com/blog/security-automation-webhooks/)) 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)&#x20;

## Design Considerations

To successfully leverage CII webhooks, it is best to first fully conceptualize a desired outcome when a user object within the CII platform is flagged for a particular Check.&#x20;

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 CII Check, such as No MFA
2. Once a day, CII 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 CII Check upon which you want to take action. &#x20;

Also, we send test messages labeled `DetailType:WebhookTest` during the webhook connectivity test. You can see the value in the existing [docs](https://docs.oort.io/integrations/webhooks#testing-the-webhook-integration).

<mark style="color:orange;">**Consumers should filter these to prevent unintended actions.**</mark>

### API Authorization

One key design consideration is how the CII webhook communication will authenticate and be authorized to the recipient platform.  CII 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. &#x20;

## CII Configuration

To create a webhook notification integration, perform the following steps:

1. Navigate to **Integrations -> Add Integration -> Webhooks**<br>

   <figure><img src="https://582105988-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqPSBzsjxd7KYg9DNVZ4l%2Fuploads%2FG1ydEfR6gYRqL8tu620G%2FWebhook%20create1%202023-08-04_13-48-46.png?alt=media&#x26;token=9d15c635-8130-4a29-a0b2-f03986a9b7ae" alt=""><figcaption></figcaption></figure>
2. Provide the following:&#x20;
   1. **Display name**
   2. **Description (optional)**
   3. **Webhook URL**<br>

      <figure><img src="https://582105988-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqPSBzsjxd7KYg9DNVZ4l%2Fuploads%2FSlV308QIRUT5D8skMNBu%2FWebhook%20create2%202023-08-04_13-48-46.png?alt=media&#x26;token=ede3abc4-ec23-4cd6-a955-22f991ffd39c" alt=""><figcaption></figcaption></figure>
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<br>

      <figure><img src="https://582105988-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqPSBzsjxd7KYg9DNVZ4l%2Fuploads%2F2Kde8snlDobIQF2SbPQ4%2FWebhook%20create3%202023-08-04_13-48-46.png?alt=media&#x26;token=3f6ac294-4aeb-4aac-a787-974f0a6adc41" alt=""><figcaption></figcaption></figure>
   3. **OAuth Client Credentials** <br>

      1. Enter the **Authorization endpoint** URL&#x20;
      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.

      <figure><img src="https://582105988-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqPSBzsjxd7KYg9DNVZ4l%2Fuploads%2FmmrLwMBIGhcSIKwYj0y2%2FWebhook%20create4%20OAuth%202023-08-04_13-48-46.png?alt=media&#x26;token=289a4530-9717-4479-917a-349598da743e" alt=""><figcaption></figcaption></figure>
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.<br>

   Click one of the following:

   * **Select checks manually**: Check the box next to everything to check for. Use the search field to search for checks by name.

     When you're finished, click **Add Checks** and select the check box next to each check to add.
   * Select checks by category: Check the box next to every **Severity** (or click **All** to select all severities), then check the box next to every **Topic** (or click **All** to select all topics).
   * Click **All failed checks** to limit notifications to failed checks only.
5. Click **Save**.

## Testing the Webhook Integration

**NOTE:**  we send test messages labeled `DetailType:WebhookTest` during the webhook connectivity test.&#x20;

<mark style="color:orange;">**Consumers should filter these to prevent unintended actions.**</mark>

**To test the connectivity of the Webhook:**&#x20;

1. On the **Integrations** page, find the row under **Notifications** section corresponding to the Webhook notification target you just created

<figure><img src="https://582105988-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqPSBzsjxd7KYg9DNVZ4l%2Fuploads%2F9IsqV2JhRMB5bVZ0nLi9%2FWebhook%20Test0%202023-08-04_13-48-46.png?alt=media&#x26;token=ba9d8ebb-880b-498b-a6b6-7871f0902d0e" alt=""><figcaption></figcaption></figure>

2. Select the Webhook notification target or click 3-dot menu on the righthand side and select **Test Connectivity**

<figure><img src="https://582105988-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqPSBzsjxd7KYg9DNVZ4l%2Fuploads%2FwAJXqTkJamAP7NXwXToN%2FWebhook%20Test1%202023-08-04_13-48-46.png?alt=media&#x26;token=49962251-54b4-4354-859e-7fa0be73b67f" alt="" width="233"><figcaption></figcaption></figure>

3. This will send a basic test message to the webhook destination to confirm that connectivity is successful. The contents of the message will be:

```
{
  "version": "0",
  "id": "9d26ad04-2db5-e72c-db29-b5e4935e3ca0",
  "detail-type": "WebhookTest",
  "source": "ad4ccde2-4c41-45e5-92be-8e4af81a9796__5c836a54",
  "account": "227542035969",
  "time": "2025-04-20T07:06:56Z",
  "region": "us-east-2",
  "resources": [],
  "detail": {
    "id": "b54e4399-d7ad-45d3-9526-424a18c5ddd3",
    "checkId": "oort-test-check-id",
    "title": "Cisco Identity Intelligence Failing Check Event Test",
    "severity": "critical",
    "login": "user1@example.com",
    "explainabilityDetails": [
      {
        "key": "userTitle",
        "value": "Tester"
      },
      {
        "key": "userTrustLevel",
        "value": "QUESTIONABLE"
      }
    ],
    "userTrustLevel": "QUESTIONABLE",
    "checkTopics": [
      "identity_threat_insight"
    ],
    "checkTags": [
      "tag1",
      "tag2"
    ],
    "frameworks": [
      "framework1",
      "framework2"
    ],
    "published": "2025-04-20T07:06:56.251Z"
  }
}

```

**To test what a custom message for a specific failing check will look like:**

1. Go to a specific check page and click **Customize Messages**
2. Customize the message as desired and select **Save**
3. Click the **Test** button for the Webhook Notification Target to send a test message to verify the custom message looks as intended&#x20;

## Enabling Webhook Notifications for Checks

When the webhook integration is created, <mark style="color:orange;">**it is not assigned to any check notifications by default.**</mark>  Nothing will be sent via the webhook until it is enabled in the desired Oort Check(s). &#x20;

To enable it, navigate to the desired Check details page and expand the dropdown next to **Check Settings** on the top-right corner of the page. Select the checkbox for the webhook target that you would like enabled for the given check.&#x20;

<figure><img src="https://582105988-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqPSBzsjxd7KYg9DNVZ4l%2Fuploads%2FnVRb1u368f31AvdhfGoo%2FWebhook%20Enable1%202023-08-04_13-48-46.png?alt=media&#x26;token=b736f6e9-087e-441d-be62-86569413601a" alt=""><figcaption></figcaption></figure>

## New Features

2024.09.19

CII has added \`checkTags\` to the webhook event payload.  This allows organizations to add custom tags to specific checks (see below), and then pass these through the events to their webhook destination for further automation or classification.

<figure><img src="https://582105988-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqPSBzsjxd7KYg9DNVZ4l%2Fuploads%2FYavAJ1y84GgRwo2KB8Kq%2Fimage.png?alt=media&#x26;token=0c3b91af-9d8f-4b3d-8255-36001f8e3e4f" alt=""><figcaption></figcaption></figure>

## Example Event Payload

As of April 17, 2025, we have added the following fields to the new payload:\
\
• login - the login value of the user failing the check\
• userTrustLevel - the trust level of the user <https://docs.oort.io/user-trust-level>\
• checkTopics - as appears on the check page in CII\
• frameworks - as appears on the check page in CII\
• checkTags - tags added to the check by the customer

An example of the payload for new users failing the Unused Application for a User check would look as follows:

```
{
  "version": "0",
  "id": "3a9f6ca8-08af-43f0-827a-ceda239d16f9",
  "detail-type": "FAILED_CHECK",
  "source": "908040f3-da74-4a58-8029-e5b57f80c5e8__969f9802",
  "account": "227542035969",
  "time": "2025-04-10T06:26:40Z",
  "region": "us-east-2",
  "resources": [],
  "detail": {
    "id": "8ca60986-39ae-4b43-b512-f594271a3971",
    "checkId": "unused-user-apps",
    "title": "Unused Application for a User",
    "severity": "low",
    "login": "zdrojewski.ryker@simubiz.com",
    "checkTags": [],
    "checkTopics": [
      "compliance",
      "identity_posture_insight"
    ],
    "frameworks": [
      "nist_csf_pr_ac_4"
    ],
    "explainabilityDetails": [
      {
        "value": "devops engineer",
        "key": "userTitle"
      },
      {
        "value": "FAVORABLE",
        "key": "userTrustLevel"
      },
      {
        "value": "{\"applications\":[{\"name\":\"workday\"},{\"name\":\"five9 plus adapter for salesforce\"},{\"name\":\"workday sandbox\"}]}",
        "key": "context"
      }
    ],
    "userTrustLevel": "FAVORABLE",
    "published": "2025-04-10T06:26:40.577Z"
  }
}
```

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 CII has direct integrations for [Azure Sentinel](https://docs.oort.io/integrations/azure-sentinel-siem-integration) or Snowflake security data lakes.)&#x20;

### Direct Message payload example

An example of the payload for a direct message to a specific end user, or the end user's manager, who is failing a check would look as follows:

```
      {
        recipient: recipientEmail,
        checkId: checkMetadata.id,
        title: checkMetadata.title,
        severity: checkMetadata.severity,
        directMessage,
        referenceVideoUrls: WizerVideoUrl
      }
```