Skip to content
lokalise-webhooks-events logo

Lokalise Webhooks Events

lokalise-webhooks-events

Implement Lokalise webhook handling and event processing.

SKILL.md

Full skill instructions

Lokalise Webhooks Events

Overview

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:

curl -X POST "https://api.lokalise.com/​api2/​projects/​${PROJECT_ID}/​webhooks" \
  -H "X-Api-Token: ${LOKALISE_API_TOKEN}" \
  -H "Content-Type: application/​json" \
  -d '{
    "url": "https://your-app.example.com/​webhooks/​lokalise",
    "branch": "main",
    "events": [
      "project.key.added",
      "project.key.modified",
      "project.translation.updated",
      "project.translation.proofread",
      "project.imported",
      "project.exported",
      "project.contributor.added",
      "project.contributor.deleted"
    ],
    "event_lang_map": [
      {"event": "project.translation.updated", "lang_iso_codes": ["en", "fr", "de"]}
    ]
  }'

The response includes a secret field — store this securely. You need it to verify incoming payloads.

To scope webhooks to specific languages, use event_lang_map. This prevents noise from languages you do not manage.

2. Know the Event Types

EventFires WhenKey Payload Fields
project.key.addedNew key createdkey.key_id, key.key_name, key.platforms
project.key.modifiedKey name, tags, or metadata changedkey.key_id, key.key_name, key.modifications
project.key.deletedKey removedkey.key_id, key.key_name
project.key.comment.addedComment added to a keykey.key_id, comment.comment
project.translation.updatedTranslation value changedtranslation.translation_id, translation.value, language.lang_iso
project.translation.proofreadTranslation marked as reviewedtranslation.translation_id, language.lang_iso
project.importedFile uploaded to projectimport.filename, import.format
project.exportedFile downloaded/​exportedexport.filename
project.contributor.addedNew team member addedcontributor.email, contributor.role
project.contributor.deletedTeam member removedcontributor.email

3. Understand the Webhook Payload Structure

Every webhook POST delivers this structure:

{
  "event": "project.translation.updated",
  "project": {
    "id": "123456789.abcdefgh",
    "name": "My Project"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "Jane Translator"
  },
  "language": {
    "lang_id": 640,
    "lang_iso": "fr",
    "lang_name": "French"
  },
  "translation": {
    "translation_id": 98765,
    "key_id": 11223,
    "value": "Bonjour le monde",
    "is_reviewed": false,
    "modified_at": "2026-03-19T10:30:00Z"
  },
  "created_at": "2026-03-19T10:30:01Z"
}

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.

5. Route Events by Type

interface LokaliseWebhookPayload {
  event: string;
  project: { id: string; name: string };
  user: { email: string; full_name: string };
  language?: { lang_iso: string; lang_name: string };
  key?: { key_id: number; key_name: string; platforms: string[] };
  translation?: {
    translation_id: number;
    value: string;
    is_reviewed: boolean;
  };
  import?: { filename: string; format: string };
  contributor?: { email: string; role: string };
  created_at: string;
}

type EventHandler = (payload: LokaliseWebhookPayload) => Promise<void>;

const eventHandlers: Record<string, EventHandler> = {
  "project.key.added": async (payload) => {
    console.log(`New key: ${payload.key!.key_name}`);
    // Notify translators, update local cache, trigger CI
  },

  "project.translation.updated": async (payload) => {
    const { translation, language } = payload;
    console.log(
      `Translation updated [${language!.lang_iso}]: ${translation!.value}`
    );
    // Trigger rebuild, invalidate CDN cache, update OTA bundle
  },

  "project.imported": async (payload) => {
    console.log(`File imported: ${payload.import!.filename}`);
    // Kick off translation memory update, notify reviewers
  },

  "project.contributor.added": async (payload) => {
    console.log(`New contributor: ${payload.contributor!.email}`);
    // Send onboarding info, assign default language pairs
  },
};

async function routeEvent(payload: LokaliseWebhookPayload): Promise<void> {
  const handler = eventHandlers[payload.event];
  if (handler) {
    await handler(payload);
  } else {
    console.log(`Unhandled event type: ${payload.event}`);
  }
}

6. Implement Idempotency

Lokalise may retry webhooks on network failure, sending duplicates. Track processed events:

const processedEvents = new Set<string>();

async function routeEventIdempotent(
  payload: LokaliseWebhookPayload
): Promise<void> {
  // Create a unique key from event + timestamp + relevant IDs
  const eventKey = `${payload.event}:${payload.created_at}:` +
    `${payload.translation?.translation_id ?? payload.key?.key_id ?? ""}`;

  if (processedEvents.has(eventKey)) {
    console.log(`Duplicate event skipped: ${eventKey}`);
    return;
  }

  processedEvents.add(eventKey);
  // For production: use Redis SET with TTL instead of in-memory Set
  // await redis.set(`webhook:${eventKey}`, "1", "EX", 86400);

  await routeEvent(payload);
}

Output

  • Webhook registered in Lokalise project with selected event subscriptions
  • Express endpoint verifying x-secret header on every request
  • Event router dispatching to type-specific handlers
  • Idempotency guard preventing duplicate processing
  • Immediate 200 response with async background processing

Error Handling

IssueCauseSolution
Invalid signatureWrong secret or secret rotatedRe-check LOKALISE_WEBHOOK_SECRET against Lokalise project settings
Timeout (8 seconds)Synchronous processing too slowRespond 200 immediately, process in background
Duplicate eventsLokalise retried after network issueImplement idempotency with event key deduplication
Missing eventsEvent type not subscribedUpdate webhook via PUT /​projects/​{id}/​webhooks/​{webhook_id}
Webhook disabledToo many consecutive failuresCheck Lokalise dashboard; webhook auto-disables after repeated errors

Examples

List Existing Webhooks

curl -X GET "https://api.lokalise.com/​api2/​projects/​${PROJECT_ID}/​webhooks" \
  -H "X-Api-Token: ${LOKALISE_API_TOKEN}"

Update Webhook Events

curl -X PUT "https://api.lokalise.com/​api2/​projects/​${PROJECT_ID}/​webhooks/​${WEBHOOK_ID}" \
  -H "X-Api-Token: ${LOKALISE_API_TOKEN}" \
  -H "Content-Type: application/​json" \
  -d '{
    "events": [
      "project.translation.updated",
      "project.translation.proofread",
      "project.imported"
    ]
  }'

Delete a Webhook

curl -X DELETE "https://api.lokalise.com/​api2/​projects/​${PROJECT_ID}/​webhooks/​${WEBHOOK_ID}" \
  -H "X-Api-Token: ${LOKALISE_API_TOKEN}"

Test Webhook Locally with ngrok

# 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

Resources

Next Steps

For handling errors returned by webhook API calls, see lokalise-common-errors.

More skills from jeremylongshore

openrouter-compliance-review logo
jeremylongshore/claude-code-plugins-plus-skills

openrouter-compliance-review

Review OpenRouter integration for regulatory compliance (SOC2, GDPR,

2.8K 0
View
maintainx-data-handling logo
jeremylongshore/claude-code-plugins-plus-skills

maintainx-data-handling

Data synchronization, ETL patterns, and data management for MaintainX.

2.8K 0
View
groq-core-workflow-a logo
jeremylongshore/claude-code-plugins-plus-skills

groq-core-workflow-a

Execute Groq primary workflow: chat completions with tool use and JSON

2.8K 0
View
validating-csrf-protection logo
jeremylongshore/claude-code-plugins-plus-skills

validating-csrf-protection

Validate CSRF protection implementations for security gaps. Use when

2.8K 0
View
api-contract logo
jeremylongshore/claude-code-plugins-plus-skills

api-contract

Configure this skill should be used when the user asks about "API contract",

2.8K 0
View
ideogram-incident-runbook logo
jeremylongshore/claude-code-plugins-plus-skills

ideogram-incident-runbook

Execute Ideogram incident response with triage, mitigation, and postmortem.

2.8K 0
View
gamma-sdk-patterns logo
jeremylongshore/claude-code-plugins-plus-skills

gamma-sdk-patterns

Reusable patterns for the Gamma REST API (no SDK exists).

2.8K 0
View
deepgram-sdk-patterns logo
jeremylongshore/claude-code-plugins-plus-skills

deepgram-sdk-patterns

Apply production-ready Deepgram SDK patterns for TypeScript and Python.

2.8K 0
View
openrouter-upgrade-migration logo
jeremylongshore/claude-code-plugins-plus-skills

openrouter-upgrade-migration

Migrate to OpenRouter from direct provider APIs or upgrade between SDK/model

2.8K 0
View
openrouter-common-errors logo
jeremylongshore/claude-code-plugins-plus-skills

openrouter-common-errors

Diagnose and fix common OpenRouter API errors. Use when encountering

2.8K 0
View
linear-cost-tuning logo
jeremylongshore/claude-code-plugins-plus-skills

linear-cost-tuning

Optimize Linear API usage, reduce unnecessary calls, and maximize

2.8K 0
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View