Implement Lokalise webhook handling and event processing.
Use when setting up webhook endpoints, handling translation events,
or building automation based on Lokalise notifications.
Trigger with phrases like "lokalise webhook", "lokalise events",
"lokalise notifications", "handle lokalise events", "lokalise automation".
Lokalise webhooks push real-time notifications to your endpoint when translation events occur — keys created, translations updated, files uploaded, contributors added. This skill covers creating webhooks via the API, handling each event type, verifying webhook secrets, and routing events to appropriate handlers.
Prerequisites
Lokalise project with admin or manager role (required for webhook creation)
HTTPS endpoint accessible from the internet (Lokalise rejects HTTP URLs)
Express.js or equivalent HTTP framework
Webhook secret for payload verification (generated during webhook creation)
Instructions
1. Create a Webhook via the API
Register your endpoint with Lokalise using POST /projects/{project_id}/webhooks:
The top-level event field determines which nested objects are present. Always check event first before accessing nested fields.
4. Build an Express Handler with Secret Verification
Lokalise signs webhook payloads with the secret from step 1. Verify it using the x-secret header:
import express from "express";
import type { Request, Response, NextFunction } from "express";
const app = express();
const WEBHOOK_SECRET = process.env.LOKALISE_WEBHOOK_SECRET!;
// Parse raw body for signature verification
app.use("/webhooks/lokalise", express.json());
// Verify webhook secret
function verifyLokaliseSecret(
req: Request,
res: Response,
next: NextFunction
): void {
const secret = req.headers["x-secret"] as string;
if (!secret || secret !== WEBHOOK_SECRET) {
console.error("Webhook signature verification failed");
res.status(401).json({ error: "Invalid webhook secret" });
return;
}
next();
}
app.post(
"/webhooks/lokalise",
verifyLokaliseSecret,
async (req: Request, res: Response) => {
// Respond immediately — Lokalise times out after 8 seconds
res.status(200).json({ received: true });
// Process asynchronously
try {
await routeEvent(req.body);
} catch (error) {
console.error("Webhook processing failed:", error);
}
}
);
Responding with 200 before processing is critical. Lokalise retries on timeout (8s) and treats non-2xx as failure. Process the event asynchronously to avoid timeouts.
# Terminal 1: Start your server
npm run dev # Express on port 3000
# Terminal 2: Expose via ngrok
ngrok http 3000
# Use the ngrok HTTPS URL when creating the webhook:
# https://abc123.ngrok-free.app/webhooks/lokalise
