Test Worldline webhooks locally

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

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

This guide covers Worldline Direct and its Merchant Portal.

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 Worldline Direct test account with access to the Merchant Portal
• 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 keyId = process.env.WORLDLINE_WEBHOOK_KEY_ID;
  const secret = process.env.WORLDLINE_WEBHOOK_SECRET;
  if (!keyId || !secret) {
    return new Response("Missing Worldline webhook settings", { status: 500 });
  }

  const body = await request.text();
  const received = request.headers.get("x-gcs-signature") ?? "";
  const receivedKeyId = request.headers.get("x-gcs-keyid");
  const expected = createHmac("sha256", secret).update(body, "utf8").digest("base64");

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

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

  const event = JSON.parse(body) as { type: string; id: string };
  console.log(`Received Worldline event: ${event.type} (${event.id})`);

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

npm run dev

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

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

WORLDLINE_WEBHOOK_KEY_ID=replace-with-your-webhooks-id
WORLDLINE_WEBHOOK_SECRET=replace-with-your-secret-webhook-key

Check it worksCopy Anchor Link

Ask Worldline to send a test message with the SendTestWebhook endpoint of the Direct API. Send {"url": "https://my-worldline-app.hrzn.run/api/webhooks/worldline"} as the body, with the {merchantId} of your account in the path. If you leave url empty, Worldline uses the endpoint you added in the Merchant Portal. The call needs the API authentication described in Worldline's API documentation.

If your endpoint answers with a 2xx status, Worldline returns 204 to your request.

The Horizon terminal prints one line for the request:

  POST    200  /api/webhooks/worldline

Your app terminal prints:

Received Worldline event: payment.test (a028fc60-b04c-4119-8c87-b836967e30de)

The test message has the type payment.test. The ID differs on every call.

Worldline also offers a ValidateWebhookCredentials endpoint. It checks your webhooks key and secret against your account, and it doesn't call your server.

TroubleshootingCopy Anchor Link

The signature doesn't matchCopy Anchor Link

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

1. The secret. WORLDLINE_WEBHOOK_SECRET must be the Secret Webhook Key that matches the key ID in WORLDLINE_WEBHOOK_KEY_ID. If you selected Generate webhooks keys again, the old pair no longer works.
2. The key ID. The handler rejects a request whose X-GCS-KeyId differs from WORLDLINE_WEBHOOK_KEY_ID.
3. The body. Hash the raw body as UTF-8. Don't call request.json() first.
4. The restart. Restart npm run dev after you edit .env.local.

The request returns 404Copy Anchor Link

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

Worldline sends the same event againCopy Anchor Link

Worldline retries an event five times when it gets no 2xx response. The gaps are 10 minutes, 1 hour, 2 hours, 8 hours and 24 hours after the last attempt. Each retry carries a retry-count header, which is 0 on the first attempt. Duplicates have the same payment.id and type, so process each event idempotently.

Next stepsCopy Anchor Link

• Read Worldline's webhooks guide.
• Reserve a subdomain so your URL never changes: see pricing.