From 077d1de344b8a02792b4714d63fce8e5b3ef76fc Mon Sep 17 00:00:00 2001 From: jonathanfrappier <92055993+jonathanfrappier@users.noreply.github.com> Date: Wed, 22 Oct 2025 16:16:50 -0400 Subject: [PATCH 1/4] Add Radar webook docs --- .../set-up-alerting/webhooks/payloads.mdx | 118 ++++++++++++++++++ .../set-up-alerting/webhooks/setup.mdx | 42 +++++++ content/hcp-docs/data/docs-nav-data.json | 13 ++ 3 files changed, 173 insertions(+) create mode 100644 content/hcp-docs/content/docs/vault-radar/get-started/set-up-alerting/webhooks/payloads.mdx create mode 100644 content/hcp-docs/content/docs/vault-radar/get-started/set-up-alerting/webhooks/setup.mdx 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..87dd2ef453 --- /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 e751b7199f..85412d4ace 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" + } + ] } ] }, From c6b40af5407183ff4d1ab97675f7f51c14ffbefc Mon Sep 17 00:00:00 2001 From: Jonathan Frappier <92055993+jonathanfrappier@users.noreply.github.com> Date: Wed, 29 Oct 2025 14:42:59 -0400 Subject: [PATCH 2/4] Update content/hcp-docs/content/docs/vault-radar/get-started/set-up-alerting/webhooks/payloads.mdx Co-authored-by: Yoko Hyakuna --- .../get-started/set-up-alerting/webhooks/payloads.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 87dd2ef453..993c79dc6a 100644 --- 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 @@ -26,7 +26,7 @@ Headers included on every delivery: - `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 +## Payload schema Vault Radar sends a single-event JSON payload for each webhook delivery. From 6ab6daf838edd95a57989df87c268974403e9145 Mon Sep 17 00:00:00 2001 From: Jonathan Frappier <92055993+jonathanfrappier@users.noreply.github.com> Date: Wed, 29 Oct 2025 14:43:05 -0400 Subject: [PATCH 3/4] Update content/hcp-docs/content/docs/vault-radar/get-started/set-up-alerting/webhooks/payloads.mdx Co-authored-by: Yoko Hyakuna --- .../get-started/set-up-alerting/webhooks/payloads.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 993c79dc6a..01412c1a01 100644 --- 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 @@ -15,7 +15,7 @@ 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 +## Delivery headers Headers included on every delivery: From 91f3f243428e29296528f231a5e8e0e47bbbdbd2 Mon Sep 17 00:00:00 2001 From: Jonathan Frappier <92055993+jonathanfrappier@users.noreply.github.com> Date: Wed, 29 Oct 2025 14:43:14 -0400 Subject: [PATCH 4/4] Update content/hcp-docs/content/docs/vault-radar/get-started/set-up-alerting/webhooks/payloads.mdx Co-authored-by: Yoko Hyakuna --- .../get-started/set-up-alerting/webhooks/payloads.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 01412c1a01..6d45338f1b 100644 --- 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 @@ -4,7 +4,7 @@ description: >- Interpreting the contents of webhook payloads --- -# 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