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_alert

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 two 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_alert event. This type of message will be sent whenever an alert triggers in InsightIDR and contains information about the alert 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_alert event

The idr_alert event is triggered whenever an alert is generated inside of InsightIDR. Just as InsightIDR can send you an email when an alert goes off in the product, you can also configure the Universal Webhook Data Exporter to send an alert to a webhook of your choice.

Request Headers

Specification
1
POST [path] HTTP/1.1
2
X-Rapid7-Event: idr_alert
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_alert
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
{
2
"timestamp": "[time of alert]",
3
"type": "[type of alert]",
4
"name": "[name of alert]",
5
"description": "[description of alert]",
6
"link": "[deep link back to IDR for the alert]",
7
"investigationID": "[the unique identifier of the investigation]",
8
"actors": {
9
"users": [
10
{
11
"name": "[the user name]"
12
"distinguishedName":"[the Active Directory distinguished name of the user]"
13
"emails":"[list of emails for the user]"
14
}
15
],
16
"assets": [
17
{
18
"hostname": "[the asset hostname]"
19
"fqdn": "[fully qualified domain name of the asset]"
20
"shortname": "[the shortname of the asset]"
21
}
22
]
23
}
24
}
Example
1
{
2
"timestamp": "2017-11-14T23:09:10.930Z",
3
"type": "AssetConnectsToNetworkHoneypot",
4
"name": "CONNECTION TO NETWORK HONEYPOT",
5
"description": "Asset abc123.myorg.com attempted 2 connections to honeypot myorg-finance-fs",
6
"link": "https://us.idr.insight.rapid7.com/op/0000000000000000#/investigations/12345678-1234-1234-1234-1234567890ab",
7
"investigationId": "12345678-1234-1234-1234-1234567890ab",
8
"actors": {
9
"users": [{
10
"name": "Amy Moss",
11
"distinguishedName": "cn=amy moss,ou=users,ou=people,dc=myorg,dc=com",
12
"emails": [
13
"amoss@myorg.com"
14
]
15
},
16
{
17
"name": "jdoe",
18
"emails": []
19
}
20
],
21
"assets": [{
22
"hostname": "abc123.myorg.com",
23
"fqdn": "abc123.myorg.com",
24
"shortname": "abc123"
25
},
26
{
27
"hostname": "xyz789",
28
"shortname": "xyz789"
29
}
30
]
31
}
32
}

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_alert 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. Optionally, select the Alerts checkbox to export asset-specific alerts from InsightIDR.
  9. Optionally, choose to trust all certificates or self-signed certificates by selecting the Certificate Settings checkboxes.
  10. 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.