웹훅 페이로드(Payloads)

웹훅 페이로드(Payloads)

웹훅은 소프트웨어 애플리케이션의 거의 실시간 이벤트를 지정된 엔드포인트에서 받을 수 있게 해주는 메커니즘이에요. 이 페이지에서는 웹훅 전달 헤더, 페이로드 스키마, HMAC 서명 검증 방법을 설명해 드릴게요.

출처: 문서

본문

웹훅 페이로드

웹훅은 소프트웨어 애플리케이션의 거의 실시간 이벤트를 지정된 엔드포인트에서 받을 수 있게 해주는 메커니즘입니다. 웹훅은 외부 API를 폴링하여 업데이트를 받는 방법을 대체할 수도 있습니다.

웹훅 연결(connection)과 구독(subscription)이 구성되면, Vault Radar는 웹훅 구독에 설정된 필터와 일치하는 이벤트를 웹훅 연결에 구성된 HTTPS 엔드포인트로 보냅니다. 이벤트는 HTTP POST 요청으로 HTTPS 엔드포인트에 전송됩니다.

전달 헤더 (Delivery headers)

모든 전달에 포함되는 헤더는 다음과 같습니다:

• Content-type: application/json; charset=utf-8 — 요청의 콘텐츠 유형.
• X-HCP-Radar-Subscription-Name — 이벤트와 매칭된 필터를 가진 구독의 사람이 읽을 수 있는 이름.
• X-HCP-Radar-Subscription-ID — 이벤트와 매칭된 필터를 가진 구독의 고유 식별자.
• X-HCP-Radar-Message-ID — 이 메시지의 고유 식별자.
• X-HCP-Radar-Signature — sha512=<hex digest> 형식의 SHA-512를 사용한 요청 본문의 HMAC 서명.
• X-HCP-Radar-Timestamp — 메시지가 HMAC 서명으로 서명될 때 추가된 UNIX 타임스탬프(에포크 이후 초).

페이로드 스키마 (Payload schema)

Vault Radar는 각 웹훅 전달에 대해 단일 이벤트 JSON 페이로드를 보냅니다.

예시 페이로드:

{
    "version": "2.0",
    "event_id": "f1f50398-8452-410a-b906-c20c8905c800",
    "type": "REPO_SCAN_MATCH",
    "sub_type": "password_assignment",
    "description": "Password assignment",
    "created": "2025-04-11T15:14:06+00:00",
    "last_updated": "2025-04-11T15:14:06+00:00",
    "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.",
    "details": null,
    "severity": "high",
    "risk_category": "secrets",
    "secret_activeness": "active",
    "secret_id": "a3f1c2d4e5b6a7c8d9e0f1a2b3c4d5e6",
    "is_monitored": true,
    "data_source_type": "GitHub Cloud",
    "data_source_name": "hashidemo",
    "resource_name": "repo-with-secret",
    "resource_uri": "https://github.com/hashidemo/repo-with-secret",
    "visibility": "private",
    "author": "[email protected]",
    "author_time": "2025-04-11T15:14:06+00:00",
    "content_id": "07a88a2b410fc53f804165c280fd38f4109b3a98",
    "content_reference": "refs/heads/main",
    "in_latest_version": true,
    "context": "file.json",
    "context_url": "<deep link to data source>",
    "portal_url": "<deep link to radar portal>",
    "managed_locations": [
        {
            "location": "vault://vault.hashicorp.cloud:8200/admin/kv?key=mysecret&version=1",
            "is_latest": true,
            "is_created_by_radar": true
        }
    ]
}

HMAC 서명 검증하기 (Validate HMAC signature)

Vault Radar는 HMAC-SHA512를 사용하여 페이로드에 서명하고, 구성된 공유 시크릿(shared secret)으로 해시한 원시 요청 본문(UTF-8)의 16진수 다이제스트(hex-encoded digest)를 생성합니다. HMAC 서명은 sha512= 접두사를 붙여 X-HCP-Radar-Signature 헤더에 넣습니다. 비밀이 구성되면 Vault Radar는 X-HCP-Radar-Signature 및 X-HCP-Radar-Timestamp 헤더를 포함합니다.

HMAC 서명을 검증하려면:

• 웹훅 연결 설정 중 Vault Radar와 공유된 웹훅 시크릿을 사용하여 원시 요청 본문의 HMAC-SHA512를 계산합니다.
• 결과를 소문자 16진수로 변환합니다.
• 계산된 값을 X-HCP-Radar-Signature 헤더의 값과 비교합니다.

다음 예시는 Python 3.12에서 내장 hmac 라이브러리를 사용해 HMAC 서명을 검증하는 방법입니다:

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)

더 알아보기 (Learn more)

• 웹훅 알림 설정하기
• 알림(Alerting) 설정하기
• HCP Vault Radar 시작하기