Test Xero webhooks locally

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

Xero checks your endpoint when you save it. This check is called Intent to receive. Your handler must pass it before Xero sends any real event, so the tunnel and the handler need to be running first.

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 Xero app in the Xero developer portal, and a Xero organisation to change data in, such as the demo company

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

type XeroWebhookPayload = {
  events?: { eventCategory: string; eventType: string; resourceId: string }[];
};

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

  const body = await request.text();
  const received = request.headers.get("x-xero-signature") ?? "";
  const expected = createHmac("sha256", webhookKey).update(body).digest("base64");

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

  if (!isValid) {
    return new Response(null, { status: 401 });
  }

  const payload = JSON.parse(body) as XeroWebhookPayload;
  for (const event of payload.events ?? []) {
    console.log(`Received Xero event: ${event.eventCategory} ${event.eventType} ${event.resourceId}`);
  }

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

XERO_WEBHOOK_KEY=replace-with-your-webhook-key

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

Check it worksCopy Anchor Link

After you save the webhook, the Horizon terminal prints at least one line for the Intent to receive check. Expect 200 for a request with a valid signature. A 401 line means Xero sent a request that failed verification:

  POST    200  /api/webhooks/xero
  POST    401  /api/webhooks/xero

The webhook becomes active when the check passes.

Then trigger a real event. Create or update a contact in your Xero organisation. A delivery can take a moment. Your app terminal prints:

Received Xero event: CONTACT UPDATE <contact id>

TroubleshootingCopy Anchor Link

The Intent to receive check failsCopy Anchor Link

• Check that the Horizon tunnel and npm run dev are both running before you save the webhook.
• Check that XERO_WEBHOOK_KEY matches the key in the developer portal, with no extra spaces or newline.
• Restart npm run dev after you edit .env.local.
• Check that the handler returns 401, not 400, for a bad signature.

The signature doesn't matchCopy Anchor Link

• Compute the HMAC over the raw body. Don't run JSON.parse and JSON.stringify first, because that can change the bytes.
• Encode the digest as base64, not hex.

The request returns 404Copy Anchor Link

The Horizon line shows [404]. The endpoint URL doesn't match your route. The file app/api/webhooks/xero/route.ts serves /api/webhooks/xero, and Xero 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.

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 contact you changed is in the organisation that your app is connected to, and that the event category is selected on the webhook.

Next stepsCopy Anchor Link

• Read Xero's webhooks documentation.
• Use the resourceUrl of an event to fetch the changed resource from the Xero API. Events carry identifiers, not the full resource.