Test Castle webhooks locally

Start your appCopy Anchor Link

Install the official Castle SDK.

npm install @castleio/sdk

Castle signs every webhook with the X-Castle-Signature header. The value is a base64 HMAC (a keyed hash) of the raw request body, with SHA-256 and your API secret as the key. The SDK's verifyWebhookSignature checks it and throws a WebhookVerificationError when it doesn't match. Pass it the raw body, so read it with request.text() before you parse it.

import { Castle, WebhookVerificationError } from "@castleio/sdk";

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

  const castle = new Castle({ apiSecret });
  const body = await request.text();

  try {
    castle.verifyWebhookSignature(
      body,
      request.headers.get("x-castle-signature") ?? undefined,
    );
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return new Response("Invalid signature", { status: 400 });
    }
    throw error;
  }

  const event = JSON.parse(body);
  console.log("Received Castle webhook:", event);

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

Store the API secret in an environment variable.

CASTLE_API_SECRET=replace-with-your-api-secret

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 Castle webhook 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-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. Castle checks the certificate of an HTTPS endpoint, and every Horizon tunnel serves HTTPS.

Add the webhook in CastleCopy Anchor Link

Castle sends a webhook when a policy or a list matches. You set it up on the page of that policy or list.

1. Open the Castle dashboard and go to the Policy page or the Lists page.
2. Open the Integrations tab.
3. Select Add Integration and choose a webhook.
4. Enter https://my-app.hrzn.run/api/webhooks/castle as the URL.
5. Save it.

Trigger an eventCopy Anchor Link

Castle documents no test button for webhooks. To get a delivery, cause the condition you attached the webhook to. Castle's own testing tip is a policy that fires when it sees an email domain such as example.com, so send a request to Castle that matches your policy.

Castle documents no resend tool. Cause the condition again for a new delivery.