> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visiqlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stream logs to Rapid7

> Continuously ship your governance decision and audit logs to a Rapid7 InsightIDR Custom Logs event source — with no Rapid7 API key.

VisIQ can forward your governance **decision** and **audit** logs to a Rapid7 InsightIDR **Custom Logs** event source, so AI governance events sit in Log Search alongside the rest of your detection estate.

Set it up at **Connectors → Log Streaming → Rapid7**. It takes about three minutes, and the last step needs you to check something in Rapid7 yourself — that is deliberate, and explained below.

***

## Before you start

* A Rapid7 InsightIDR account where you can create an event source.
* A VisIQ account with the **`settings:update`** permission — the log-destination endpoints are guarded by it.

<Note>
  Streaming starts from the moment you save. There is **no historical backfill** — logs recorded before the destination existed stay in VisIQ's audit trail and are not replayed into Rapid7.
</Note>

***

## VisIQ never asks for a Rapid7 API key

This connector has no API key field, and that is a security decision rather than a limitation.

A Rapid7 platform key would be **more** privileged than this integration needs, not less. A read-only platform key can list every log in the account **together with its ingest tokens** — handing over every write credential in your estate — and an Organization key is documented as a super key across all products. A Custom Logs webhook URL is strictly narrower: it can append events to **one** event source and do nothing else.

So the URL is the whole credential. Treat it exactly like a password:

* It is stored **envelope-encrypted** at rest and is never returned to the browser.
* The copy VisIQ keeps in its plain-text display column has **every path segment masked**, so no part of the credential reaches any surface that merely reads destination metadata.
* To revoke it, generate a new Webhook URL for the event source in InsightIDR. The old one stops working immediately.

***

## Step 1 — Create the InsightIDR event source

In InsightIDR: **Data Collection → Setup Event Source → Add Event Source → Add Raw Data → Custom Logs**.

1. Set the collection method to **Webhook**.
2. Name the event source. That name becomes the log name you will select in Log Search, so make it something you will recognise — `VisIQ Governance`, for example.
3. **Save**, then click **Copy** on the Webhook URL it generates.

There is no key to create and nothing else to configure on the Rapid7 side.

***

## Step 2 — Paste the Webhook URL

Back in VisIQ, paste the URL into **InsightIDR Webhook URL** and pick at least one stream.

| Stream        | Contents                                                             |
| ------------- | -------------------------------------------------------------------- |
| **Decisions** | Action, retrieval, and Human-in-the-Loop governance decision events. |
| **Audit**     | Platform configuration and access audit log.                         |

The URL is checked before it is accepted, and again before every send:

* It must be `https`.
* It must not carry an embedded username or password.
* Its host must be `insight.rapid7.com` or a subdomain of it — nothing else, ever. VisIQ also refuses to follow redirects, so a tampered URL cannot bounce your compliance logs to another host.

Copy the URL rather than typing it. A host like `evil-insight.rapid7.com` is **not** a subdomain of the Rapid7 apex and is rejected, as is anything with the apex buried in the middle of another domain.

<Warning>
  **Do not re-paste the masked URL the interface shows you.** A configured destination displays the redacted form. It is a structurally valid Rapid7 URL, so pasting it back would look accepted — VisIQ rejects it with an explicit error instead, because saving it would silently replace a working webhook with one that can never deliver. Leave the field blank to keep the stored URL, or re-copy a real one from InsightIDR.
</Warning>

***

## Step 3 — Confirm the test event actually arrived

This is the step other destinations do not have.

Rapid7 issues **write-only** webhook URLs with no read-back, so VisIQ cannot check that an accepted event was indexed. Worse, Rapid7's sibling ingest endpoint returns a success code for a token that does not exist — which means "the POST succeeded" does not even prove the URL is real. Showing you a green *Connected* on that basis would be a lie about a compliance stream.

So VisIQ says only that Rapid7 **accepted** the test event, hands you the unique marker it carried, and keeps **Save locked** until you confirm you found it:

1. In Rapid7, open **Log Search** and select the event source you created.
2. Run the query VisIQ shows you — it is of the form `event_id = "<marker>"`.
3. When the event is there, tick **I found the test event in Rapid7 Log Search**. Save unlocks.

If you change the URL or the streams after confirming, VisIQ re-runs the test with a **new** marker and clears your confirmation — the old attestation was about an event that is no longer the one in flight.

***

## The API behind the card

`GET` needs `settings:view`; `POST` needs `settings:update`.

```json POST /api/log-destinations theme={null}
{
  "name": "Rapid7 — InsightIDR",
  "type": "rapid7",
  "streams": ["decisions", "audit"],
  "auth_config": { "webhook_url": "https://us.api.insight.rapid7.com/…" },
  "enabled": true
}
```

Note the shape, which differs from the other destinations: Rapid7 sends **no** `endpoint_url` at all. The URL is the credential, so it travels inside `auth_config` where it is encrypted; the endpoint value you see on list surfaces is the redacted display form VisIQ derives server-side. On a later update, omitting `auth_config` keeps the stored URL unchanged.

Events are posted as newline-delimited JSON.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="VisIQ says the URL must be on insight.rapid7.com">
    Copy the Webhook URL from InsightIDR with its **Copy** button rather than retyping it. Every Rapid7 Insight ingest host is a subdomain of `insight.rapid7.com`; a look-alike host is refused by design.
  </Accordion>

  <Accordion title="The test passes but I cannot find the event in Log Search">
    Confirm you are searching the event source you just created — the name you gave it is the log name — and that the collection method is **Webhook** rather than one of the other Custom Logs methods. Do not tick the confirmation box until you have actually seen the marker; that checkbox is the only evidence VisIQ has that delivery works.
  </Accordion>

  <Accordion title="Save stays disabled">
    For Rapid7, a passing test alone does not unlock Save. You also need at least one stream selected and the delivery confirmation ticked.
  </Accordion>

  <Accordion title="VisIQ rejected the URL I copied out of its own interface">
    That was the masked display form, not the credential. Re-copy the real URL from InsightIDR, or leave the field blank to keep streaming with the one already stored.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Stream logs to Datadog" icon="dog" href="/connectors/datadog">
    The same streams into Datadog, with the intake host derived from your site.
  </Card>

  <Card title="Stream logs to Elasticsearch" icon="magnifying-glass" href="/connectors/elastic">
    The same streams into your own Elastic deployment, with a least-privilege API key.
  </Card>
</CardGroup>