Lokalise Webhooks EventsSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: lokalise-webhooks-events
description: '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".

  '
allowed-tools: Read, Write, Edit, Bash(curl:*)
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- lokalise
- webhooks
compatibility: Designed for Claude Code
---
# 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`:

```bash
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

| Event | Fires When | Key Payload Fields |
|-------|-----------|-------------------|
| `project.key.added` | New key created | `key.key_id`, `key.key_name`, `key.platforms` |
| `project.key.modified` | Key name, tags, or metadata changed | `key.key_id`, `key.key_name`, `key.modifications` |
| `project.key.deleted` | Key removed | `key.key_id`, `key.key_name` |
| `project.key.comment.added` | Comment added to a key | `key.key_id`, `comment.comment` |
| `project.translation.updated` | Translation value changed | `translation.translation_id`, `translation.value`, `language.lang_iso` |
| `project.translation.proofread` | Translation marked as reviewed | `translation.translation_id`, `language.lang_iso` |
| `project.imported` | File uploaded to project | `import.filename`, `import.format` |
| `project.exported` | File downloaded/exported | `export.filename` |
| `project.contributor.added` | New team member added | `contributor.email`, `contributor.role` |
| `project.contributor.deleted` | Team member removed | `contributor.email` |

### 3. Understand the Webhook Payload Structure

Every webhook POST delivers this structure:

```json
{
  "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:

```typescript
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

```typescript
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 Ev

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.