Test Pinwheel webhooks locally

Receive Pinwheel events on your laptop while you build, with a URL Pinwheel can reach.

Pinwheel has no dashboard form for webhooks. You register the endpoint with the Pinwheel API.

Before you beginCopy Anchor Link

• Node.js 18 or later
• A Horizon account and the CLI (see Getting started)
• A reserved subdomain for -s. Reserve one on the Subdomains page.
• A Next.js app that uses the App Router and runs on port 3000
• A Pinwheel API secret for the environment you test in

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

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

  const rawBody = Buffer.from(await request.arrayBuffer());
  const signature = request.headers.get("x-pinwheel-signature") ?? "";
  const timestamp = request.headers.get("x-timestamp") ?? "";

  const message = Buffer.concat([Buffer.from(`v2:${timestamp}:`, "utf8"), rawBody]);
  const digest = createHmac("sha256", Buffer.from(apiSecret, "utf8")).update(message).digest("hex");

  const receivedBuffer = Buffer.from(signature);
  const expectedBuffer = Buffer.from(`v2=${digest}`);
  const isValid =
    receivedBuffer.length === expectedBuffer.length &&
    timingSafeEqual(receivedBuffer, expectedBuffer);

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

  const event = JSON.parse(rawBody.toString("utf8")) as { event_id?: string };
  console.log(`Received Pinwheel event: ${event.event_id}`);

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

PINWHEEL_API_SECRET=replace-with-your-api-secret

npm run dev

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

curl -X POST "$PINWHEEL_API_URL/v1/webhooks" \
  -H "x-api-secret: $PINWHEEL_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-app.hrzn.run/api/webhooks/pinwheel",
    "status": "active",
    "enabled_events": ["account.added"]
  }'

Check it worksCopy Anchor Link

Your Horizon terminal prints one line for each event:

  POST    200  /api/webhooks/pinwheel

Your app terminal prints:

Received Pinwheel event: <event id>

If the line shows [401], see Troubleshooting.

TroubleshootingCopy Anchor Link

The signature doesn't matchCopy Anchor Link

• Check that PINWHEEL_API_SECRET is the API secret Pinwheel signs with, with no extra spaces or newline.
• Build the message as v2:<timestamp>: plus the raw body bytes. Note the colon after the timestamp.
• Read the raw bytes. Don't run JSON.parse and JSON.stringify first, because that can change the bytes.
• Restart npm run dev after you edit .env.local.

The request returns 404Copy Anchor Link

The Horizon line shows [404]. The registered URL doesn't match your route. The file app/api/webhooks/pinwheel/route.ts serves /api/webhooks/pinwheel, and Pinwheel sends POST requests.

The URL changed after a restartCopy Anchor Link

You started the tunnel without -s, so Horizon gave you a new random subdomain. Restart with -s my-app and the URL stays the same. -s needs a subdomain you reserved, see Pricing.

Pinwheel stopped sending eventsCopy Anchor Link

Pinwheel pauses an endpoint that doesn't return 200 OK for 30 consecutive days. It waits up to 15 seconds for a response. For a 5xx response or a network failure, it retries up to 5 times in the 15 minutes after the first attempt. Keep the handler fast.

Nothing reaches your appCopy Anchor Link

• Check that the Horizon terminal is still running. If its last line is Connection lost. Reconnecting…, wait for Reconnected.
• Check that the event you trigger is in enabled_events.

Next stepsCopy Anchor Link

• Read Pinwheel's webhook signature verification guide.