Universal Webhook

The Universal Webhook Data Exporter allows you to integrate Rapid7 Platform products with third-party or custom written software to respond in a specified way when events trigger on the Rapid7 Platform.

After it has been set up, the Universal Webhook data exporter will send a HTTP POST message from your collector that hosts the data exporter to the URL configured in the data exporter. The following HTTP request headers will be included in every outbound HTTP POST message to the webhook target.

Header Key

Description

Example

X-Rapid7-Event

Identifies the type of event being pushed to the webhook. The format of the request body will correspond to this event type. The InsightIDR event types are described below.

idr_investigation_created

X-Rapid7-Signature

HMAC signature of the request body content, which can be used to verify that the request was generated by the Rapid7 Platform.

QpjfToIxq/Vn9K//yWUm0//5GYeN5pZUHui93I1kcsc=

Content Type

Content type of the request body, which will always be JSON UTF-8

application/json; charset=UTF-8

Content Length

Number of bytes in the request body.

122

The Universal Webhook data exporter will send 2 types of messages. The first is a test event to confirm the URL is working. This message will be sent whenever the webhook data exporter is started, or if the configuration is changed. The second type is an idr_investigation_created event. This type of message will be sent whenever an investigation is created in InsightIDR and contains information about the investigation in the event. More details about each type of event can be found below.

Events

The Universal Webhook data exporter is responsible for delivering several types of events to the webhook that you have configured to receive the events, as listed below.

The test event

The test event will be triggered every time the Universal Webhook configuration is changed and when the data exporter is started or stopped.

Request Headers

Specification
1
POST [path] HTTP/1.1
2
X-Rapid7-Event: test
3
X-Rapid7-Signature: [signature of the request body based on the secret]
4
User-Agent: Rapid7 Webhook Data Exporter
5
Content-Length: [length of the message body]
6
Content-Type: application/json; charset=UTF-8
7
Host: [machine running webhook]
Example
1
POST /path/to/webhook HTTP/1.1
2
X-Rapid7-Event: test
3
X-Rapid7-Signature: QpjfToIxq/Vn9K//yWUm0//5GYeN5pZUHui93I1kcsc=
4
User-Agent: Rapid7 Webhook Data Exporter
5
Content-Length: 122
6
Content-Type: application/json; charset=UTF-8
7
Host: mywebhook.myorg.com

Request Body

Specification
1
{
2
  "timestamp": "[time of event]",
3
  "webhook_id": "[unique identifier of webhook]",
4
  "webhook_name": "[configured name of webhook]"
5
}
Example
1
{
2
  "timestamp": "2017-11-14T23:09:10.930Z",
3
  "webhook_id": "204711ea-e38c-4ab5-937b-f6c021fb7750",
4
  "webhook_name": "Universal Webhook"
5
}

The idr_investigation_created event

The idr_investigation_created event is triggered whenever an investigation is generated inside of InsightIDR.

Request Headers

Specification
1
POST [path] HTTP/1.1
2
X-Rapid7-Event: idr_investigation_created
3
X-Rapid7-Signature: [signature of the request body based on the secret]
4
User-Agent: Rapid7 Webhook Data Exporter
5
Content-Length: [length of the message body]
6
Content-Type: application/json; charset=UTF-8
7
Host: [machine running webhook]
Example
1
POST /path/to/webhook HTTP/1.1 
2
X-Rapid7-Event: idr_investigation_created
3
X-Rapid7-Signature: nT9gll1IqftAzBAZSHYUBCbUcun3IYInSaT2f68LaxU=
4
User-Agent: Rapid7 Webhook Data Exporter
5
Content-Length: 369
6
Content-Type: application/json; charset=UTF-8
7
Host: mywebhook.myorg.com

Request body

Specification
1
curl -X POST -H 'X-Rapid7-Event: idr_investigation_created' -H 
2
'X-Rapid7-Signature: [signature of the request body based on the secret]' 
3
-H
4
'Content-Type: application/json; charset=UTF-8' -d '{
5
  "timestamp": "[time of investigation]",
6
  "title": "[title of event]",
7
  "link": "[deep link back to IDR for the investigation]",
8
  "investigationRrn": "[the Rapid7 resource name]",
9
  "actors": {
10
    "users": [
11
      {
12
        "name": "[the user name]"
13
        "distinguishedName":"[the Active Directory distinguished name of the user]"
14
         "link":"[deep link back to IDR for the investigation]"
15
        "emails":"[list of emails for the user]"
16
      }
17
    ],
18
    "assets": [
19
      {
20
        "hostname": "[the asset hostname]"
21
        "fqdn": "[fully qualified domain name of the asset]"
22
        "shortname": "[the shortname of the asset]"
23
        "link": "[[deep link back to IDR for the investigation]]"
24
      }
25
    ]
26
  }
27
}
28
https://acme.com/your/path/here
Example
1
curl -X POST -H 'X-Rapid7-Event: idr_investigation_created' -H 
2
'X-Rapid7-Signature: nT9gll1IqftAzBAZSHYUBCbUcun3IYInSaT2f68LaxU=' -H 
3
'Content-Type: application/json; charset=UTF-8' -d
4
 {
5
  "timestamp": "2017-11-14T23:09:10.930Z",
6
  "title": "Ingress from unknown location",
7
  "link": "https://us.idr.insight.rapid7.com/op/0000000000000000#/investigations/12345678-1234-1234-1234-1234567890ab",
8
  "description": "Asset abc123.myorg.com attempted 2 connections to honeypot myorg-finance-fs",
9
  "link": "https://us.idr.insight.rapid7.com/op/0000000000000000#/investigations/12345678-1234-1234-1234-1234567890ab",
10
  "investigationId": "12345678-1234-1234-1234-1234567890ab",
11
  "investigationRrn": "rrn:investigation:us:3dcb26b5-b70f-4943-bb3c-0681fb2aef15:investigation:DXSGZF59OXJU"
12
  "actors": {
13
    "users": [{
14
        "name": "Amy Moss",
15
        "distinguishedName": "cn=amy moss,ou=users,ou=people,dc=myorg,dc=com",
16
        "link": "https://us.idr.insight.rapid7.com/op/0000000000000000#/users/12345678-1234-1234-1234-1234567890ab",
17
         "emails": "amoss@myorg.com"
18
      }
19
      {
20
        "name": "jdoe",
21
        "link": "https://us.idr.insight.rapid7.com/op/0000000000000000#/users/12345678-1234-1234-1234-1234567890ab",
22
         "emails": ""
23
      }
24
    ],
25
    "assets": [
26
      {
27
        "hostname": "abc123.myorg.com"
28
        "fqdn": "abc123.myorg.com"
29
        "shortname": "abc123"
30
        "link": "https://us.idr.insight.rapid7.com/op/0000000000000000#/asset/12345678-1234-1234-1234-1234567890ab"
31
      }
32
        "hostname": "xyz789"
33
        "shortname": "xyz789"
34
        "link": "https://us.idr.insight.rapid7.com/op/0000000000000000#/asset/12345678-1234-1234-1234-1234567890ab"
35
      }
36
    ]
37
  }
38
}
39
https://acme.com/your/path/here

Before You Begin

Before you can configure the Universal Webhook data exporter, you must set up a Web service to receive the Webhook requests. The Web service must be accessible by the Collector, which hosts the data exporter. The Web service should be configured to accept the test and idr_investigation_created messages from the data exporter, as described above. For example, you can set up an API trigger in InsightConnect to act as a Web service and it can receive the Webhook messages as required.

Configure the data exporter

After you complete the prerequisite steps, you must add the data exporter in InsightIDR.

To configure the new data exporter in InsightIDR:

  1. From the left menu, go to Data Collection and click Data Exporters.
  2. Click Add Data Exporter.
  3. Select Universal Webhook as the Data Exporter Type.
  4. Choose your collector. You can also name your data exporter if you want.
  5. Provide the URL that you previously configured. For security reasons, Rapid7 recommends using HTTPS as the protocol whenever possible.
  6. If the secret is not already provided, enter it in the Secret field.
  7. Optionally, add any additional headers needed for your webhook HTTP POST request. These will be included in each webhook message, in addition to the headers listed at the top of this page.
    • For example, if your endpoint requires an authorization key, you could add it here with “Authorization” as the key and whatever the appropriate key was in your webhook as the value.
  8. If you are creating a new Data Exporter, Investigation is selected by default. If you are editing a legacy data exporter, you can choose between Investigations including Legacy Detection Rules or Investigations including the Detection Rules Library and Legacy Detection Rules.

Changing Data Export Type cannot be undone

If you switch an existing data exporter’s export type from Investigations including Legacy Detection Rules to Investigations including the Detection Rules Library and Legacy Detection Rules, you cannot switch back.

  1. Optionally, choose to trust all certificates or self-signed certificates by selecting the Certificate Settings checkboxes.
  2. Click Save.

What is the "Secret" field?

When configuring the data exporter, you will see a pre-populated field titled "Secret," which is the HMAC verification key for this data exporter. Each webhook message sent from this data exporter will include a X-Rapid7-Signature in the request header which will be populated with a value that was generated using the data exporter's secret. For improved security, the webhook receiving the message can us this signature along with the known secret to verify that the message is a genuine message from the data exporter.