웹훅 만들고 관리하기

웹훅 만들고 관리하기 (Create and manage webhooks)

이 주제는 HashiCorp Cloud Platform(HCP)에서 프로젝트 리소스의 수명 주기 이벤트를 외부 시스템에 알려주는 웹훅(webhook)을 구현하는 방법을 설명해요.

출처: 문서

본문

웹훅 보기와 관리하기 (Viewing and managing webhooks)

HCP 사이드바에서 프로젝트를 클릭하고 Project settings > Webhooks를 선택해 Webhooks 페이지를 엽니다. 페이지에는 기존 웹훅이 표시돼요.

웹훅 만들기 (Creating a webhook)

웹훅을 만들려면 다음 단계를 완료해요.

Project settings > Webhooks를 클릭해요. Webhooks 페이지가 나타나요.
Create webhook을 클릭해요. Create webhook 페이지가 나타나요.
Name: 웹훅의 이름을 지정해요. 이 필드는 필수예요.
Description: 웹훅에 대한 설명을 추가해요. 설명은 다른 사람이 웹훅의 목적을 이해하는 데 유용해요. 이 필드는 선택사항이에요.
Webhook URL: 웹훅 페이로드의 대상(destination)을 지정해요. 대상은 HTTP 또는 HTTPS POST 요청을 수락해야 하며 페이로드를 사용할 수 있어야 해요. 이 필드는 필수예요.
Token: HCP가 웹훅 요청에 서명하는 데 사용하는 임의의 시크릿 문자열을 지정해요. 자세한 내용은 Webhook Authenticity를 참고하세요. 웹훅 구성을 저장한 후에는 토큰을 볼 수 없어요. 이 필드는 선택사항이에요.
Events: Webhook URL 필드에 지정된 대상으로 보내려는 이벤트를 지정해요. 모든 이벤트 또는 특정 이벤트에 대한 페이로드를 보낼 수 있어요. 보낼 수 있는 이벤트는 리소스를 소유한 서비스에 따라 달라져요. 이벤트 유형과 페이로드는 해당 서비스의 웹훅 문서를 참고하세요.
Create webhook을 클릭해요.

웹훅 활성화와 검증 (Enabling and verifying a webhook)

웹훅을 활성화하거나 비활성화하려면:

Enable webhook: 웹훅을 활성화해요. HCP는 검증 페이로드(verification payload)를 보내 웹훅 구성을 검증하려 시도하며, 검증이 성공할 때만 웹훅을 활성화해요. 검증이 성공하려면 대상이 200~299 범위의 HTTP 응답 코드로 응답해야 해요. 검증이 실패하면 HCP가 오류 메시지를 표시하고 구성은 비활성화 상태로 유지돼요.
Disable webhook: 웹훅을 비활성화해요. HCP는 대상 URL로 페이로드 전달을 중단해요.

웹훅 페이로드 (Webhook payload)

웹훅 페이로드는 다음 정보를 포함해요.

Resource ID: 이벤트와 관련된 리소스의 ID예요.
Resource name: 이벤트와 관련된 리소스의 이름이에요.
Event ID: <service>.event:<random string> 형식으로 서비스가 생성한 이벤트의 고유 식별자예요. 예: packer.event:t79BRg8WhTmDPBRM
Event action: 이 이벤트의 작업 유형이에요. 예: create
Event description: 이벤트 설명이에요. 예: Created version
Event source: 이벤트의 소스예요. 예: hashicorp.packer.version 이벤트가 하위(descendant) 리소스에서 온 것이라면 이벤트 소스는 웹훅이 구독하는 리소스 유형과 다를 수 있어요. 예를 들어 웹훅이 hashicorp.packer.registry를 구독하고 hashicorp.packer.version 같은 하위 리소스의 이벤트를 받을 수 있어요.
Event version: 전송되는 이벤트 페이로드의 버전이에요.
Event payload: 리소스의 수명 주기 이벤트에 대한 정보가 담긴 페이로드예요.

리소스를 소유한 서비스가 페이로드를 작성해요. 특정 페이로드에 대한 자세한 내용은 HCP Webhook Events Documentation에 링크된 해당 서비스의 웹훅 문서를 참고하세요.

서드파티 서비스는 HCP 웹훅 페이로드 밖의 추가 필드를 요구할 수 있어요. 이런 유형의 서비스와 통합하려면 페이로드를 변환할 수 있는 미들웨어 웹훅을 통합해야 해요. 미들웨어는 HCP 웹훅 요청에 200 OK로 응답하고 변환된 페이로드를 서드파티 대상 URL로 전달해야 합니다. 자세한 도움은 서드파티 서비스의 문서를 참고하세요.

다음은 hashicorp.packer.version 리소스의 예시 페이로드예요.

{
    "resource_id": "01HAVMCV8XWW945TNKT2KPYSN1",
    "resource_name": "packer/project/ff99bac7-eaec-40a1-8f55-5eb05e789401/registry/01HAVMCV8XWW945TNKT2KPYSN1",
    "event_id": "packer.event:MtCpPwmkdPpD8qqfMRhJ",
    "event_action": "create",
    "event_description": "Created version",
    "event_source": "hashicorp.packer.version",
    "event_version": "1",
    "event_payload": {
        "actor": {
            "principal_id": "ac7295a2-85ef-4594-b4c6-3a1f8b733f1a",
            "type": "TYPE_USER",
            "user": {
                "email": "[email protected]",
                "id": "d8f45791-460d-434e-8a40-f627e752276a",
                "name": "User Name"
            }
        },
        "bucket": {
            "id": "01HAVMDEAXNF5RYDDSK5R39HDP",
            "slug": "test"
        },
        "version": {
            "fingerprint": "01HAVMD1YBM4PA1KHNYFAYJREM",
            "id": "01HAVMD63G58XDA8JKS2B8J871",
            "revocation_author": "",
            "revocation_message": "",
            "revoke_at": "",
            "status": "RUNNING",
            "version": "v0"
        },
        "organization_id": "6a171c1d-c7cd-4047-ba1a-92d686dde2ed",
        "project_id": "ff99bac7-eaec-40a1-8f55-5eb05e789401",
        "registry": {
            "id": "01HAVMCV8XWW945TNKT2KPYSN1"
        },
    }
}

검증 페이로드 (Verification payload)

HCP는 웹훅 URL과 토큰을 만들기·활성화·갱신하기 전에 웹훅 구성이 유효한지 검증해요. 검증이 성공하려면 대상이 검증 페이로드에 200~299 범위의 HTTP 응답 코드로 응답해야 해요.

{
    "event_id": "webhook.event:mlizg1TCaSsrJ2hOXZMmS",
    "event_action": "test",
    "event_description": "Verification",
    "event_source": "hashicorp.webhook.verification",
    "resource_id": "",
    "resource_name": "",
    "event_version": "1",
    "event_payload": {}
}

event_id는 각 검증 페이로드마다 고유해요.

웹훅 진위성 (Webhook authenticity)

시크릿 토큰을 포함하는 웹훅 구성의 경우, HCP 웹훅 요청에는 SHA-512 다이제스트 알고리즘으로 토큰에서 계산된 HMAC 서명이 담긴 X-HCP-Webhook-Signature 헤더가 포함됩니다. 수신 서비스는 서명을 검증할 책임이 있어요.

다음 예시는 Ruby로 HMAC을 검증합니다.

token = SecureRandom.hex
hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha512"), token, @request.body)
fail "Invalid HMAC" if hmac != @request.headers["X-HCP-Webhook-Signature"]

Terraform으로 웹훅 관리하기 (Managing webhooks with Terraform)

HCP Terraform 프로바이더를 사용해 웹훅을 만들고 관리할 수 있어요. 자세한 내용은 HCP Terraform provider의 hcp_notifications_webhook 리소스 문서를 참고하세요.

HCP 웹훅 이벤트 문서 (HCP Webhook Events Documentation)

보낼 수 있는 이벤트에 대한 자세한 내용은 해당 서비스의 웹훅 문서를 참고하세요.

HCP Packer Webhook Events

더 알아보기 (Learn more)

프로젝트 (Projects) — 프로젝트 기반 접근 분리 방법을 살펴보세요.
조직 (Organizations) — 조직 관리 방법을 확인해 보세요.