Add Radar webook docs

content/hcp-docs/content/docs/vault-radar/get-started/set-up-alerting/webhooks/payloads.mdx

@@ -0,0 +1,118 @@
+---
+page_title: Webhook - payloads
+description: >-
+  Interpreting the contents of webhook payloads
+---
+
+# Webhook Payloads
+
+Webhooks provide a mechanism to receive near-real-time events from software
+applications to a specified endpoint. Webhooks may be used as a substitute for
+polling an external API for updates.
+
+Once a webhook connection and a subscription have been configured, Vault Radar
+will send events that match the filter set on the webhook subscription to the
+HTTPS endpoint configured on the webhook connection. Events are sent to the
+HTTPS endpoint as an HTTP POST request.
+
+## Delivery Headers
+
+Headers included on every delivery:
+
+- `Content-type: application/json; charset=utf-8` — the request content type.
+- `X-HCP-Radar-Subscription-Name` — the human readable name of the subscription whose filter matched the event.
+- `X-HCP-Radar-Subscription-ID` — the unique identifier for the subscription whose filter matched the event.
+- `X-HCP-Radar-Message-ID` — the unique identifier for this message.
+- `X-HCP-Radar-Signature` — HMAC signature of the request body using SHA-512 in the format `sha512=<hex digest>`.
+- `X-HCP-Radar-Timestamp` — UNIX timestamp (seconds since epoch) added when the message is signed with an HMAC signature.
+
+## Payload Schema
+
+Vault Radar sends a single-event JSON payload for each webhook delivery.
+
+|Field               |Type      |Description                                                                       |
+|--------------------|----------|----------------------------------------------------------------------------------|
+|`version`           | `string` | Webhook payload version                                                          |
+|`event_id`          | `string` | Unique identifier for the event                                                  | 
+|`event_type`        | `string` | High level type for the event                                                    | 
+|`event_subtype`     | `string` | Optional subtype for the event                                                   | 
+|`description`       | `string` | Full description of the finding                                                  | 
+|`summary`           | `string` | Short summary text for display                                                   | 
+|`severity`          | `string` | Severity label for the finding                                                   | 
+|`risk_category`     | `string` | Risk category assigned by Radar                                                  | 
+|`data_source`       | `object` | Information about the data source that produced the finding                      | 
+|`event_details`     | `object` | Additional fields vary by `data_source.type`                                     | 
+|`managed_locations` | `list`   | List of managed locations in Vault. See [Copy leaked secrets into HashiCorp Vault](/hcp/docs/vault-radar/remediate-secrets/copy-secrets) for more information |
+|`links`             | `object` | Deep links to Vault Radar and data source                                        | 
+
+**Example payload:**
+
+<CodeBlockConfig hideClipboard>
+
+```json
+{
+    "version": "1.0",
+    "event_id": "f1f50398-8452-410a-b906-c20c8905c800",
+    "event_type": "REPO_SCAN_MATCH",
+    "event_subtype": "password_assignment",
+    "description": "Password assignment",
+    "summary": "Discovered some form of secret assignment in the resource. Best practice is to store the secret in a secret manager and revoke this found secret.",
+    "severity": "high",
+    "risk_category": "secrets",
+    "data_source": {
+        "type": "GitHub Cloud",
+        "name": "hashidemo",
+        "resource": "repo-with-secret"
+    },
+    "event_details": {
+        "author": "[email protected]",
+        "author_time": "2025-04-11 15:14:06+00:00",
+        "commit_hash": "07a88a2b410fc53f804165c280fd38f4109b3a98",
+        "repo_file_path": "file.json"
+    },
+    "managed_locations": {
+        "hashicorp_vault": [
+            {
+                "location": "vault://vault.hashicorp.cloud:8200/admin/kv?key=mysecret&version=1",
+                "is_latest": true,
+                "is_created_by_radar": true
+            }
+        ]
+    },
+    "links": {
+        "vault_radar_link": "<deep link to radar portal>",
+        "data_source_provider_link": "<deep link to data source>"
+    }
+```
+
+</CodeBlockConfig>
+
+## Validate HMAC signature
+
+Vault Radar signs payloads using HMAC-SHA512 to generate a hex-encoded digest of
+the raw request body (UTF-8) hashed with the configured shared secret. The HMAC
+signature is placed in the `X-HCP-Radar-Signature` header with the `sha512=`
+prefix. Vault Radar will include the `X-HCP-Radar-Signature` and
+`X-HCP-Radar-Timestamp` headers when a secret is configured.
+
+To validate the HMAC signature:
+
+1. Compute HMAC-SHA512 of the raw request body using the webhook secret shared with Vault Radar during webhook connection setup.
+
+1. Convert the result to lowercase hexadecimal.
+
+1. Compare the computed value with the value in the `X-HCP-Radar-Signature` header.
+
+The following example validates the HMAC signature in Python 3.12 using the built-in `hmac` library:
+
+```python
+import hmac
+import hashlib
+
+secret = b"my-secret-key"
+message = b"message to verify"
+signature = "sha512=expected_signature_hex"
+
+computed = hmac.new(secret, message, hashlib.sha512).hexdigest()
+is_valid = hmac.compare_digest(signature.split('=')[1], computed)
+```

content/hcp-docs/content/docs/vault-radar/get-started/set-up-alerting/webhooks/setup.mdx

@@ -0,0 +1,42 @@
+---
+page_title: Setup alerting - webhook
+description: >-
+  Set up alerts using webhooks for Vault Radar.
+---
+
+# Set up alerting - webhook
+
+@include 'beta-feature.mdx'
+
+You can receive alerts from HCP Vault Radar to a custom HTTPS endpoint using a webhook.
+
+## Prerequisites
+
+- An HTTPS endpoint configured to receive HTTP POST requests
+
+## Create a webhook connection
+
+1. Click **Settings** from the side navigation. 
+
+1. Under the **Integration** menu, click **Webhook**.
+
+1. Click **+ Add connection**.
+
+1. Enter a unique name for the connection and a valid HTTPS endpoint configured to receive HTTP POST requests.
+
+1. Enter a token used to generate HMAC tokens for Vault Radar events for authorization.
+
+   Vault Radar will send a test message to your specified HTTPS endpoint validate the connection details.
+
+## Create a webhook subscription
+
+1. Click the **Connection Name**.
+
+1. Click **+ Subscription**.
+
+1. Enter a name for the subscription and the saved filter(s) you would like the subscription to use.
+
+1. Click **Test & Save**.
+
+   Vault Radar events matching your filters will send events via webhooks to the
+   specified HTTPS endpoint.

content/hcp-docs/data/docs-nav-data.json

@@ -890,6 +890,19 @@
               {
                 "title": "Splunk",
                 "path": "vault-radar/get-started/set-up-alerting/splunk"
+              },
+              {
+                "title": "Webhook <sup>Beta</sup>",
+                "routes": [
+                  {
+                    "title": "Set up",
+                    "path": "vault-radar/get-started/set-up-alerting/webhooks/setup"
+                  },
+                  {
+                    "title": "Validate payloads",
+                    "path": "vault-radar/get-started/set-up-alerting/webhooks/payloads"
+                  }
+                ]
               }
             ]
           },