Integration guides

Node.js with Express

Complete path for a Node.js backend with Express, based on the reference example.

The reference example node-express/ of the examples repo (Node.js 20.6+, the only dependency is Express) covers reports, own status, complaints, reviews, device check and the webhook, including ordering of events by decidedAt.

Shell
cd limenia-examples/node-express && npm install && npm test
# the user sets LIMENIA_API_KEY and LIMENIA_WEBHOOK_SECRET (e.g. in .env, never committed)
npm start

Routes

Route of your backend Calls Limenia
POST /reports POST /v1/reports
GET /me/moderation-status GET /v1/subjects/{id}/status
POST /appeals, GET /appeals/:appealId POST /v1/appeals, GET /v1/appeals/{appealId} (status only for the person who complained)
POST /reviews, GET /reviews/:reviewId POST /v1/reviews, GET /v1/reviews/{reviewId} (status only for the author)
POST /devices/request-hash, POST /devices/check POST /v1/devices/check
POST /limenia/webhook called by Limenia

Files: src/limenia.js (client with retries), src/signature.js, src/events.js (per event, dedupe, ordering), src/actions.js (placeholders), src/auth.js (login stub, replace it), src/device.js, src/app.js.

Webhook route

The webhook route must read the raw body, so register it before express.json():

JavaScript
app.post("/limenia/webhook", express.raw({ type: () => true, limit: "1mb" }), async (req, res) => {
  const rawBody = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
  try {
    verifySignature({ header: req.get("Limenia-Signature"), rawBody, secrets: webhookSecrets });
  } catch (err) {
    if (err instanceof WebhookSignatureError) return res.status(401).json({ code: err.code });
    throw err;
  }
  const event = JSON.parse(rawBody.toString("utf8"));
  try {
    await withDeadline(handleEvent(event), 8_000); // Limenia waits 10 s
    res.sendStatus(204);
  } catch {
    res.sendStatus(503); // Limenia retries
  }
});
app.use(express.json({ limit: "1mb" }));

verifySignature (from src/signature.js):

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

export function verifySignature({ header, rawBody, secrets, now = Date.now() / 1000 }) {
  if (!header) throw new WebhookSignatureError("missing_signature");
  let timestamp;
  const signatures = [];
  for (const part of header.split(",")) {
    const eq = part.indexOf("=");
    if (eq < 1) throw new WebhookSignatureError("malformed_signature");
    const key = part.slice(0, eq).trim();
    const value = part.slice(eq + 1).trim();
    if (key === "t") {
      if (timestamp !== undefined) throw new WebhookSignatureError("malformed_signature");
      timestamp = value;
    } else if (key === "v1") signatures.push(value);
  }
  if (timestamp === undefined || !/^\d{1,12}$/.test(timestamp) || signatures.length === 0)
    throw new WebhookSignatureError("malformed_signature");
  if (Math.abs(now - Number(timestamp)) > 300) throw new WebhookSignatureError("timestamp_out_of_range");
  for (const secret of secrets) {
    const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
    for (const signature of signatures) {
      if (/^[0-9a-fA-F]{64}$/.test(signature) && timingSafeEqual(expected, Buffer.from(signature, "hex"))) return;
    }
  }
  throw new WebhookSignatureError("signature_mismatch");
}

Forwarding a report

Reporter from the login, allowlisted fields only:

JavaScript
app.post("/reports", requireUser, async (req, res) => {
  const b = req.body ?? {};
  const report = {
    source: "user",
    reasonCategory: b.reasonCategory,
    reasonText: b.reasonText,
    goodFaith: b.goodFaith,
    reporter: { externalUserId: req.user.id }, // from the login, never from the app
    subject: b.subject,                         // better: load content and author from your database
    content: b.content,
    externalReportId: b.externalReportId,
  };
  await forward(res, () =>
    limenia.request("POST", "/v1/reports", { body: report, idempotencyKey: idempotencyKey(req, res, "report") }),
  );
});

forward passes Limenia’s status, problem body and Retry-After to the app unchanged; no answer at all becomes 502 limenia_unreachable. MemoryEventStore and the device hash store are in memory: replace them with your database or Redis before running more than one instance.