Test Hygraph webhooks locally

Start your appCopy Anchor Link

When a webhook has a secret key, Hygraph sends a gcms-signature header. It looks like sign=<signature>, env=<environment>, t=<timestamp>. The signature is an HMAC SHA-256 (a keyed hash) of a JSON payload built from the body, the environment name and the timestamp.

Hygraph's @hygraph/utils package does that work. Install it.

npm install @hygraph/utils

Read the raw body with request.text() and pass it in unchanged.

import { verifyWebhookSignature } from "@hygraph/utils";

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

  const body = await request.text();
  const signature = request.headers.get("gcms-signature") ?? "";

  const isValid = verifyWebhookSignature({ body, signature, secret });
  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  const { operation, data } = JSON.parse(body);
  console.log(`Received Hygraph ${operation} for ${data.__typename}`);

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

Pick a secret and store it in an environment variable. Use a random, high-entropy string.

HYGRAPH_WEBHOOK_SECRET=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 Hygraph webhook would point at a dead URL after a restart. Reserved subdomains are a paid feature, see Pricing.

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

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

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

Add the webhook in HygraphCopy Anchor Link

1. Open Project Settings, then Automation, then Webhooks.
2. Select Add webhook.
3. Enter a name and a description.
4. Turn on the option to include the payload.
5. Enter https://my-app.hrzn.run/api/webhooks/hygraph as the URL.
6. Select the content model, the stage and the action you want to listen for.
7. Enter the same value as HYGRAPH_WEBHOOK_SECRET in the secret key field.
8. Select Add webhook.

Trigger an eventCopy Anchor Link

Hygraph's docs describe no test button and no resend. Trigger a real event instead: create, update or publish an entry of the content model you selected.

To inspect a call, select View logs next to the webhook. Each entry shows the timestamp, the HTTP status, the content model, the action and the duration. Select an entry to see the request and response. Hygraph keeps logs for 7 days.