Test HCP Terraform webhooks locally

Start your appCopy Anchor Link

For generic webhooks with a token, HCP Terraform adds an X-TFE-Notification-Signature header. It holds the HMAC-SHA512 digest of the request body, hex encoded. The key is your token. Read the raw body with request.text() and compare in constant time.

import { createHmac, timingSafeEqual } from "node:crypto";

export async function POST(request: Request) {
  const token = process.env.TFE_NOTIFICATION_TOKEN;
  if (!token) {
    return new Response("Missing TFE_NOTIFICATION_TOKEN", { status: 500 });
  }

  const body = await request.text();
  const received = request.headers.get("x-tfe-notification-signature") ?? "";
  const expected = createHmac("sha512", token).update(body).digest("hex");

  const receivedBuffer = Buffer.from(received);
  const expectedBuffer = Buffer.from(expected);
  const isValid =
    receivedBuffer.length === expectedBuffer.length &&
    timingSafeEqual(receivedBuffer, expectedBuffer);

  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  const payload = JSON.parse(body);
  console.log(`Received HCP Terraform notification with keys: ${Object.keys(payload).join(", ")}`);

  return new Response("ok", { status: 200 });
}

Pick a token and store it in an environment variable. Use a random, high-entropy string. HCP Terraform doesn't show the token again after you save the notification, so keep it in .env.local.

TFE_NOTIFICATION_TOKEN=replace-with-a-long-random-string

Start the app on port 3000.

npm run dev

Start a tunnelCopy Anchor Link

Use -s with a subdomain you reserved. Without it, the subdomain is random and changes every run, so your notification would point at a dead URL after a restart. Reserve it first on the Subdomains page. Reserved subdomains are a paid feature, see Pricing.

hrzn tunnel http://localhost:3000 -s my-terraform-app

HORIZON: Tunnel connected
  URL          https://my-terraform-app.hrzn.run (reserved)
  Forwarding   http://localhost:3000
  Request log  https://hrzn.run/dashboard/tunnels/my-terraform-app

Your public URL is https://my-terraform-app.hrzn.run. Keep this terminal open.

Add the notification in HCP TerraformCopy Anchor Link

1. Sign in to HCP Terraform and select your workspace.
2. Select Settings, then Notifications.
3. Select Create a Notification.
4. For Destination, choose the generic webhook option. Slack, Microsoft Teams and email use other formats.
5. Enter a Name.
6. Set Webhook URL to https://my-terraform-app.hrzn.run/api/webhooks/terraform.
7. Set Token to the same value as TFE_NOTIFICATION_TOKEN.
8. Under Run Events, choose all events or pick specific ones: Created, Planning, Needs Attention, Applying, Completed and Errored.
9. Select Create a notification.

When you save a notification that is enabled, HCP Terraform sends a verification request to your URL. Your handler must answer with a 2xx status. Keep npm run dev and the tunnel running, or the verification fails and HCP Terraform leaves the notification disabled.

Send a test eventCopy Anchor Link

1. Open the notification on its detail page.
2. Select the Send a Test link.

To see the result, select the Last Response box on the same page.

For a real event, queue a run in the workspace. HCP Terraform sends a notification for each run event you selected.