Test Chargify webhooks locally

Receive Chargify events on your laptop while you build, with a public HTTPS URL Chargify can reach. Chargify is now called Maxio Advanced Billing, and this guide covers both names.

Horizon has no Chargify integration. Chargify sends webhooks to a public URL, and Horizon provides that URL.

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.
• An Advanced Billing site where you can open Config, Settings
• A Next.js app that uses the App Router and runs on port 3000

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

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

  const body = await request.text();
  const received = request.headers.get("x-chargify-webhook-signature-hmac-sha-256") ?? "";
  const expected = createHmac("sha256", sharedKey).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 fields = new URLSearchParams(body);
  const webhookId = request.headers.get("x-chargify-webhook-id");
  console.log(`Received Chargify event: ${fields.get("event")} (webhook ${webhookId})`);

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

npm run dev

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

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

CHARGIFY_SHARED_KEY=replace-with-your-shared-key

Check it worksCopy Anchor Link

Send a test event from Advanced Billing. Two options exist:

• To test one endpoint, open the endpoint's Actions dropdown and select Test. This sends a minimal payload.
• To test an event type, go to Tools, then Webhook Testing. Select an event type and an endpoint, then send it. Advanced Billing sends a realistic payload for that event.

The Horizon terminal prints one line for the request:

  POST    200  /api/webhooks/chargify

Your app terminal prints one line such as Received Chargify event: test (webhook 12345). Maxio's Webhooks Panel shows the delivery from their side.

To check the signature code without Advanced Billing, use the example from Maxio's docs. Set CHARGIFY_SHARED_KEY=123, restart npm run dev, and send the example body with its documented signature:

curl -X POST https://my-billing-app.hrzn.run/api/webhooks/chargify \
  -H "X-Chargify-Webhook-Signature-Hmac-Sha-256: 19826d51b9f866b26eda1f154de192593360f8d0bcb63df8a28540a5dcf733f1" \
  -d 'payload[chargify]=testing&event=test'

Put your real shared key back afterwards.

TroubleshootingCopy Anchor Link

The signature doesn't matchCopy Anchor Link

The Horizon line shows [401]. Check these in order:

1. The key. CHARGIFY_SHARED_KEY must equal the Shared Key of the site that owns the endpoint. Each site has its own key. Did you restart the dev server after you edited .env.local?
2. The body. Hash the raw body. Don't pass it through request.formData() or URLSearchParams first.
3. The header. Read X-Chargify-Webhook-Signature-Hmac-Sha-256, the HMAC-SHA-256 one.

The request returns 404Copy Anchor Link

The Horizon line shows [404]. The route file app/api/webhooks/chargify/route.ts serves /api/webhooks/chargify. Check the target URL for typos, and make sure the file exports POST.

The URL changed after a restartCopy Anchor Link

You started the tunnel without -s, so Horizon gave you a new random subdomain. Advanced Billing still sends events to the old URL. Restart with -s, and edit the endpoint if the URL differs.

Advanced Billing sends the same webhook againCopy Anchor Link

Anything other than 200 OK, and any timeout, triggers up to six attempts in total. The gaps run from about 10 seconds up to about 15 minutes. Return 200 first and do slow work afterwards.

Next stepsCopy Anchor Link

• Read Maxio's guide to webhook configuration and testing.
• Reserve a subdomain so your URL never changes: see pricing.