Skip to content
WebsiteDocumentationDashboard ↗LibertyJS repo ↗npm package ↗GitHub organization ↗

LibertyTools / Docs

Forward events to your server

Forwarding sends matching ER:LC events to an HTTP endpoint you control. It works alongside hosted commands and Poll clients, so you can keep an existing system while adding LibertyTools features.

Choose a delivery format

Signed Proxy

LibertyTools sends a normalized event body and signs it. Choose this for a new handler built specifically for LibertyTools.

Raw Mirror

LibertyTools preserves the original ER:LC request body and official signature headers. Choose this for a handler that already understands direct ER:LC webhooks.

If you are unsure, start with Signed Proxy. The dashboard shows an example event and the exact headers for the selected format.

Set up a destination

  1. Create a connection and put its webhook URL in your ER:LC server settings.
  2. In Outputs → Forward destinations, choose Custom handler and enter a name and your receiver's HTTP or HTTPS URL.
  3. Choose Signed Proxy or Exact ER:LC copy. Use the format preview to implement your receiver.
  4. Choose the event and command filters, keep Forward events to this handler checked, then click Add destination.
  5. For Signed Proxy, open More → Send test event. For Exact ER:LC copy, trigger a genuine ER:LC event or use the connection-check flow below.
  6. Inspect Events → Forwarding deliveries. Use Edit to change settings later; an active handler does not need to be prepared again.

Use custom commands alongside Melonly

Choose Melonly in the Handler setup menu. It fills in the direct receiver URL https://erlc-wh.melon.ly/, Exact ER:LC copy format, all-event routing, and connection checks. Link the same ER:LC server in Melonly itself, then click Add destination. The preset does not configure your Melonly account.

You can use LibertyTools hosted commands and Melonly together. The command-routing and filter fields control which matching events are forwarded. Exact copy preserves a whole signed request: if ER:LC batches several events together, forwarding that request also forwards its other events.

Read delivery health

A new handler starts in probation. A successful 2xx response moves it to active. Failed deliveries are retried and stop after 30 minutes or the attempt limit. Repeated failures can pause the handler. After fixing a paused handler, click Retry forwarding. For Signed Proxy, that sends a test event; for Exact ER:LC copy, follow the real-check flow below.

Forwarding is queued so a slow destination does not stop healthy outputs. The queue is bounded, and losses are counted in the dashboard. Return 2xx after safely accepting an event, and handle retries without duplicate side effects.

Exact ER:LC copy and webhook checks

Exact ER:LC copy preserves the original body bytes, content type, and official signature headers. The destination host and transport headers change for the new request, and LibertyTools adds tracking headers.

In Edit, check Forward ER:LC connection checks and save. This includes genuine WebhookProbe events even when other filters exclude them. Turning checks off does not block ordinary matching events.

  1. Enable connection checks in Edit.
  2. If the handler is paused, click Retry forwarding. This enables it in probation without sending a fabricated request. Active handlers do not need this step.
  3. Save the connection's LibertyTools webhook URL again in ER:LC's Event Webhook setting to trigger a genuine signed check.
  4. Inspect Events → Forwarding deliveries. A successful response moves the handler to active.

Authenticate the event

Signed Proxy uses HMAC-SHA256 with your destination's signing secret. Sign the timestamp, a literal dot, and the exact raw body bytes; compare the hex digest using a constant-time comparison before parsing JSON. Reject timestamps more than five minutes away from your clock.

X-Liberty-Event-Id: evt_example
X-Liberty-Delivery-Id: del_example
X-Liberty-Timestamp: 1792160507
X-Liberty-Signature: v1=<hex hmac>

Signed bytes: <timestamp>.<raw request body>

For Raw Mirror, verify ER:LC's X-Signature-Timestamp and X-Signature-Ed25519 headers against the exact original body. LibertyJS provides an official ER:LC signature verifier. The receiver below is for Signed Proxy only.

Run a Signed Proxy receiver

Use Node.js 22 or newer. This example needs no npm packages. Create a folder named liberty-receiver, open a terminal there, and save signed-proxy-receiver.mjs in it:

import http from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';
import { pathToFileURL } from 'node:url';

const MAX_BYTES = 1024 * 1024;
export function createReceiver({ secret, onEvent, now = Date.now }) {
  if (typeof secret !== 'string' || !secret.trim()) throw new Error('Set LIBERTY_SIGNING_SECRET in your private .env file.');
  const server = http.createServer((req, res) => {
    if (req.method !== 'POST' || req.url !== '/events') {
      res.writeHead(404).end();
      req.resume();
      return;
    }
    const timestamp = req.headers['x-liberty-timestamp'];
    const signature = req.headers['x-liberty-signature'];
    if (typeof timestamp !== 'string' || !/^\d{10}$/.test(timestamp) ||
        Math.abs(now() - Number(timestamp) * 1000) > 300_000 ||
        typeof signature !== 'string' || !/^v1=[a-f0-9]{64}$/.test(signature)) {
      res.writeHead(401).end();
      req.resume();
      return;
    }
    const chunks = [];
    let bytes = 0;
    req.on('error', () => { if (!res.headersSent) res.writeHead(400).end(); });
    req.on('data', chunk => {
      bytes += chunk.length;
      if (bytes > MAX_BYTES) {
        chunks.length = 0;
        if (!res.headersSent) res.writeHead(413).end();
      } else chunks.push(chunk);
    });
    req.on('end', async () => {
      if (bytes > MAX_BYTES) return;
      const body = Buffer.concat(chunks);
      const expected = createHmac('sha256', secret).update(timestamp).update('.').update(body).digest();
      if (!timingSafeEqual(expected, Buffer.from(signature.slice(3), 'hex'))) {
        res.writeHead(401).end();
        return;
      }
      let event;
      try { event = JSON.parse(body.toString('utf8')); }
      catch { res.writeHead(400).end(); return; }
      if (!event || typeof event.id !== 'string' || typeof event.type !== 'string') {
        res.writeHead(400).end();
        return;
      }
      try {
        // Complete your work, or save it to a durable queue, before acknowledging.
        await onEvent(event);
        res.writeHead(204).end();
      } catch { res.writeHead(500).end(); }
    });
  });
  server.requestTimeout = 10_000;
  server.headersTimeout = 5_000;
  server.keepAliveTimeout = 5_000;
  server.maxRequestsPerSocket = 100;
  return server;
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const server = createReceiver({
    secret: process.env.LIBERTY_SIGNING_SECRET,
    // Demonstration only: this logs events; it does not persist or deduplicate them.
    onEvent: event => console.log('Accepted event:', event.type, event.id)
  });
  const port = Number(process.env.PORT || 3000);
  const host = process.env.HOST || '127.0.0.1';
  server.listen(port, host, () => console.log(`Receiver listening at http://${host}:${port}/events`));
}

Create a plain text file named .env beside it. Use a made-up secret for the local test; for real deliveries, copy the signing secret shown when you create a Signed Proxy destination in Outputs. If you no longer have it, rotate that destination's secret and update your receiver.

LIBERTY_SIGNING_SECRET=replace-with-your-destination-signing-secret
PORT=3000

Name the file .env, not .env.txt. Add .env to your .gitignore. Start the receiver from that folder:

node --env-file=.env signed-proxy-receiver.mjs

Expect Receiver listening at http://127.0.0.1:3000/events. Keep the terminal open.

Test it without ER:LC

Save send-signed-proxy-test.mjs in the same folder. Open a second terminal in that folder and run:

node --env-file=.env send-signed-proxy-test.mjs

The sender should report Local signature test passed (HTTP 204), and the receiver should print an accepted event. This only sends a fake event to your local receiver; it sends no in-game command. A wrong secret returns 401. If the connection is refused, start the receiver first and check the port.

Connect it to LibertyTools

LibertyTools cannot reach localhost, 127.0.0.1, or a private LAN address on your computer. Host the receiver on a server with a public URL, or use a public tunnel or reverse proxy that forwards requests to http://127.0.0.1:3000. Enter the public URL ending in /events as a Signed Proxy destination in Outputs. Both public HTTP and HTTPS are supported.

Replace your test secret in .env with the destination's actual signing secret, restart the receiver, and choose More → Send test event on the Signed Proxy handler. If it is paused, use Retry forwarding instead. Expect a 204 delivery and an accepted event in the receiver's terminal. The process must stay running for real deliveries.