Test Modern Treasury webhooks locally

Receive Modern Treasury events on your laptop while you build, with a public HTTPS URL Modern Treasury can reach.

Horizon has no Modern Treasury integration. Modern Treasury 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.
• A Modern Treasury organization where you can open Developers
• A Next.js app that uses the App Router and runs on port 3000

npm install modern-treasury

import ModernTreasury from "modern-treasury";

export async function POST(request: Request) {
  const client = new ModernTreasury();
  const body = await request.text();

  let isValid = false;
  try {
    isValid = client.webhooks.validateSignature(body, request.headers);
  } catch {
    isValid = false;
  }

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

  const topic = request.headers.get("x-topic");
  const webhookId = request.headers.get("x-webhook-id");
  console.log(`Received Modern Treasury webhook: ${topic} (${webhookId})`);

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

MODERN_TREASURY_API_KEY=replace-with-your-api-key
MODERN_TREASURY_ORGANIZATION_ID=replace-with-your-organization-id

npm run dev

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

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

MODERN_TREASURY_API_KEY=replace-with-your-api-key
MODERN_TREASURY_ORGANIZATION_ID=replace-with-your-organization-id
MODERN_TREASURY_WEBHOOK_KEY=replace-with-your-webhook-key

Check it worksCopy Anchor Link

Create an event in your Modern Treasury account, such as a new payment order. Modern Treasury sends a webhook for it to your endpoint.

The Horizon terminal prints one line for the request:

  POST    200  /api/webhooks/modern-treasury

Your app terminal prints one line such as Received Modern Treasury webhook: payment_order (<webhook id>).

To see the delivery on Modern Treasury's side, open Developers, then Webhooks, and select your endpoint. Its overview page lists the delivery attempts. Select View Details on one to see its headers, body and destination URL.

TroubleshootingCopy Anchor Link

The signature doesn't matchCopy Anchor Link

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

1. The key. MODERN_TREASURY_WEBHOOK_KEY must equal the webhook key of this endpoint. Each endpoint has its own key. Did you restart the dev server after you edited .env.local?
2. The body. Validate the raw body. Don't call request.json() first.
3. The header. Modern Treasury sends the signature in X-Signature.

The handler throws about a missing API key or organization IDCopy Anchor Link

new ModernTreasury() needs MODERN_TREASURY_API_KEY and MODERN_TREASURY_ORGANIZATION_ID as well as the webhook key. Set all three in .env.local.

The request returns 404Copy Anchor Link

The Horizon line shows [404]. The route file app/api/webhooks/modern-treasury/route.ts serves /api/webhooks/modern-treasury. Check the endpoint 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. Modern Treasury still sends events to the old URL. Restart with -s, and edit the endpoint if the URL differs.

Next stepsCopy Anchor Link

• Read Modern Treasury's guide to verifying a webhook event.
• Reserve a subdomain so your URL never changes: see pricing.