diff --git a/content/hcp-docs/content/docs/vault-radar/get-started/set-up-alerting/webhooks/payloads.mdx b/content/hcp-docs/content/docs/vault-radar/get-started/set-up-alerting/webhooks/payloads.mdx new file mode 100644 index 0000000000..6d45338f1b --- /dev/null +++ b/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=`. +- `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:** + + + +```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": "someone@myorg.com", + "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": "", + "data_source_provider_link": "" + } +``` + + + +## 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) +``` diff --git a/content/hcp-docs/content/docs/vault-radar/get-started/set-up-alerting/webhooks/setup.mdx b/content/hcp-docs/content/docs/vault-radar/get-started/set-up-alerting/webhooks/setup.mdx new file mode 100644 index 0000000000..40492a5cee --- /dev/null +++ b/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. diff --git a/content/hcp-docs/data/docs-nav-data.json b/content/hcp-docs/data/docs-nav-data.json index e4ec42e9da..3987639ed2 100644 --- a/content/hcp-docs/data/docs-nav-data.json +++ b/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 Beta", + "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" + } + ] } ] },