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.
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 startRoutes
| 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():
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):
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:
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.