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 for more information
`links`	`object`	Deep links to Vault Radar and data source

Example payload:

{
    "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": "<deep link to radar portal>",
        "data_source_provider_link": "<deep link to data source>"
    }

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:

Compute HMAC-SHA512 of the raw request body using the webhook secret shared with Vault Radar during webhook connection setup.
Convert the result to lowercase hexadecimal.
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:

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)