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

You'll need access to a web service that can be reached via a URL that is accessible by the collector which will host the data exporter and is ready to accept test and idr_alert messages from the data exporter. For example, you can configure a Komand workflow to accept webhook triggers.

How to Configure This Data Exporter

  1. From your dashboard, select Data Collection on the left hand menu.
  2. When the Data Collection page appears, click the Setup Event Source dropdown and choose Add Event Source.
  3. From the “Security Data” section, click the Data Exporter icon. The “Add Event Source” panel appears.
  4. Choose your collector and event source. You can also name your event source 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 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 choose to export asset-specific Alerts from InsightIDR by checking the Alerts box.
  9. Optionally choose to trust all certificates and/or self-signed certificates by checking the appropriate boxes.
  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.