Create and manage webhooks

This topic describes how to implement webhooks in HashiCorp Cloud Platform (HCP) that notify external systems about a project resource's lifecycle events.

Viewing and managing webhooks

Click on a project in the HCP sidebar and choose Project settings > Webhooks to open the Webhooks page. The page shows any existing webhooks.

Creating a webhook

Complete the following steps to create a webhook:

Click Project settings > Webhooks. The Webhooks page appears.
Click Create webhook. The Create webhook page appears.
Configure the following fields:
- Name: Specify a name for the webhook. This field is required.
- Description: Add a description for the webhook. Descriptions are useful for helping others understand the purpose of the webhook. This field is optional.
- Webhook URL: Specify the destination for the webhook payload. The destination must accept HTTP or HTTPS POST requests and should be able to use the payload. This field is required.
- Token: Specify an arbitrary secret string that HCP uses to sign its webhook requests. Refer to Webhook Authenticity for details. You cannot view the token after you save the webhook configuration. This field is optional
- Events: Specify the events that you want to send to the destination specified in the Webhook URL field. You can send payloads for all events or only for specific events. The events that are available to send are specific to the services that own the resources. Refer to the service's webhook documentation for events type and payloads.
Click Create webhook.

Enabling and verifying a webhook

To enable or disable a webhook:

Click Project settings > Webhooks. The Webhooks page appears.
Click the ellipses menu next to the webhook you want to manage. Depending on the current state of the webhook, one of the following options appears:
- Enable webhook: Enables the webhook. HCP attempts to verify the webhook configuration by sending a verification payload, and only enables the webhook if the verification succeeds. For a verification to be successful, the destination must respond with an HTTP response code in the 200 - 299 range. If verification fails, HCP displays the error message and the configuration remains disabled.
- Disable webhook: Disables the webhook. HCP stops delivering payloads to the destination URL.

Webhook payload

Webhook payloads contain the following information:

Resource ID: The ID of the resource the event is related to.
Resource name: The resource name of the resource the event is related to.
Event ID: The unique identifier for the event generated by the services with the format <service>.event:<random string>. For example, packer.event:t79BRg8WhTmDPBRM.
Event action: The type of action of this event. For example, create.
Event description: The event description. For example, Created iteration.
Event source: The source of the event. For example, hashicorp.packer.iteration. Event source might not be the same type as the resource that the webhook is subscribed to if the event is from a descendant resource. For example, webhooks are subscribed to a hashicorp.packer.registry and receive events for descendent resources such as a hashicorp.packer.iteration.
Event version: The version of the event payload that is being sent.
Event payload: The payload with the information about the resource's lifecycle event.

The service that owns the resource writes the payload. Refer to the service's webhook documentation for more information.

Third-party services may require additional fields that are outside of the HCP webhook payload. To integrate with these types of services, you must integrate a middleware webhook capable of translating payloads. The middleware must respond 200 OK to HCP webhook requests and forward the translated payload to the third-party destination URL. Refer to the documentation for your third-party services for assistance.

The following example payload is from the hashicorp.packer.iteration resource:

{
    "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 iteration",
    "event_source": "hashicorp.packer.iteration",
    "event_version": "1",
    "event_payload": {
        "actor": {
            "principal_id": "ac7295a2-85ef-4594-b4c6-3a1f8b733f1a",
            "type": "TYPE_USER",
            "user": {
                "email": "user@email.com",
                "id": "d8f45791-460d-434e-8a40-f627e752276a",
                "name": "User Name"
            }
        },
        "bucket": {
            "id": "01HAVMDEAXNF5RYDDSK5R39HDP",
            "slug": "test"
        },
        "iteration": {
            "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 verifies that the webhook configuration is valid before creating, enabling, or updating a webhook URL and token. For the verification to be successful, the destination must respond to the verification payload with an HTTP response code in the 200 - 299 range.

{
    "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": {}
}

The event_id is unique to each verification payload.

Webhook authenticity

For webhook configurations that include a secret token, HCP webhook requests include an X-HCP-Webhook-Signature header, which contains an HMAC signature computed from the token using the SHA-512 digest algorithm. The receiving service is responsible for validating the signature.

The following example verifies the HMAC using Ruby:

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"]