Webhook events

Events

These are the events you can subscribe to for each project, with payload examples.

When using our Node SDK, you can take advantage of the exported types for webhooks, for example:

import type { WebhookProjectKeyAdded } from "@lokalise/node-api";

const event: WebhookProjectKeyAdded = {
  // ...
};

project.imported

Fires whenever translation files were uploaded to a project.

// project.imported

{
  "event": "project.imported",
  "import": {
    "filename": "ru.yml",
    "format": "yml",
    "inserted": 231,
    "updated": 0,
    "skipped": 0
  },
  "import_options": {
    "replace_line_breaks": false,
    "convert_placeholders": true,
    "replace_modified": false,
    "key_tags": [
      "tag1", "tag2"
    ],
    "tag_keys_inserted": true,
    "tag_keys_updated": true,
    "tag_keys_skipped": false,
    "detect_icu_plurals": true,
    "fill_empty_with_keys": false,
    "hide_from_contributors": false,
    "diff_by_file": false,
    "use_tm": false,
    "cleanup": false
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "develop"
  },
  "language": {
    "id": 597,
    "iso": "ru",
    "name": "Russian"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

Please note that for every translation file uploaded to Lokalise, you will receive a separate event. The number of events received will match the number of files uploaded.

You can also subscribe to the complementary webhook events project.keys.added, project.keys.modified and project.translations.updated to learn what data has been added or modified by the upload, sparing further queries to the Lokalise API. The webhook payload will include an action field with the import.file value, so you can easily identify that this action caused the data changes.

project.exported

Fires whenever translation files were downloaded from a project.

// project.exported

{
  "event": "project.exported",
  "export": {
    "type": "json",
    "filename": "files/export/138c1ffa0ad94848f01f980e7f2f2af19d1bd553/67d1a7ff9cab3a57e32ea71c4561a58d/locales.zip",
    "platform": "Web"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.copied

Fires when a project is copied.

// project.copied

{
  "event": "project.copied",
  "action": "copy_project",
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "new_project": {
    "id": "435744046465ddb63bff26.20365706",
    "name": "Onboarding copy"
  },
  "user": {
    "full_name": "John Doe",
    "email": "[email protected]"
  },
  "created_at": "2023-05-18 10:11:40",
  "created_at_timestamp": 1684397500
}

project.deleted

Fires when a project has been deleted.

// project.deleted

{
  "event": "project.deleted",
  "project": {
    "id": "123.abc",
    "name": "Sample project"
  },
  "user": {
    "full_name": "John Doe",
    "email": "[email protected]"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.snapshot

Fires when a project snapshot was created.

// project.snapshot

{
  "event": "project.snapshot",
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.branch.added

Fires when a new project branch was created.

// project.branch.added

{
  "event": "project.branch.added",
  "project": {
    "id": "123.abc",
    "name": "Sample Project"
  },
  "branch": {
    "id": 1234,
    "name": "develop"
  },
  "user": {
    "full_name": "John Doe",
    "email": "[email protected]"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.branch.deleted

Fires when a project branch was deleted.

// project.branch.deleted

{
  "event": "project.branch.deleted",
  "project": {
    "id": "123.abc",
    "name": "Sample Project"
  },
  "branch": {
    "id": 1234,
    "name": "develop"
  },
  "user": {
    "full_name": "John Doe",
    "email": "[email protected]"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.branch.merged

Fires when two project branches were merged.

// project.branch.merged

{
  "event": "project.branch.merged",
  "project": {
    "id": "123.abc",
    "name": "Sample Project"
  },
  "branch": {
    "id": 1234,
    "name": "develop"
  },
  "target_branch": {
    "id": 5678,
    "name": "sprint_20210103"
  },
  "affected_keys": {
    "inserted_count": 4,
    "updated_count": 10
  },
  "user": {
    "full_name": "John Doe",
    "email": "[email protected]"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.languages.added

Fires when a new language was added to a project.

// project.languages.added

{
  "event": "project.languages.added",
  "languages": [
    {
      "id": 734,
      "iso": "it",
      "name": "Italian"
    }
  ],
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.language.removed

Fires when a language was removed from a project.

// project.language.removed

{
  "event": "project.language.removed",
  "language": {
    "id": 734,
    "iso": "it",
    "name": "Italian"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.language.settings_changed

Fires when language settings have been changed.

// project.language.settings_changed

{
  "event": "project.language.settings_changed",
  "language": {
    "id": 734,
    "iso": "it",
    "name": "Italian"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.key.added

Fires when a new translation key has been added to a project.

// project.key.added

{
  "event": "project.key.added",
  "key": {
    "id": 16307699,
    "name": "test.title",
    "base_value": "Hello, world!",
    "tags": [
      "home"
    ],
    "filenames": {
      "ios": null,
      "android": null,
      "web": "messages.%LANG_ISO%.xlf",
      "other": null
    },
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.keys.added

Fires when new translation keys have been added to a project through a bulk action. Each event will include up to a maximum of 300 keys in the payload.

// project.keys.added

{
  "event": "project.keys.added",
  "action": "lokalise",
  "keys": [
    {
      "id": 28707699,
      "name": "test.title",
      "base_value": "Hello, world!",
      "tags": [
        "home_page"
      ],
      "filenames": {
        "ios": null,
        "android": null,
        "web": "messages.%LANG_ISO%.xlf",
        "other": null
      },
      "previous_name": null,
      "hidden": false,
      "screenshots": [
        "4103370"
      ]
    },
    {
      "id": 28746571,
      "name": "test.line1",
      "base_value": "How are you?",
      "tags": [
        "home_page"
      ]
    },
    {
      "id": 28745716,
      "name": "test.line2",
      "base_value": "It's good to see you.",
      "tags": [
        "home_page"
      ]
    }
  ],
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "develop"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2023-03-07 12:02:01",
  "created_at_timestamp": 1678186921
}

project.key.modified

Fires when a translation key has been modified in a project.

// project.key.modified

{
  "event": "project.key.modified",
  "key": {
    "id": 16307699,
    "name": "test.title_modified",
    "previous_name": "test.title",
    "filenames": {
      "ios": "ios_%LANG_ISO%.strings",
      "android": null,
      "web": "%LANG_ISO%.json",
      "other": null
    },
    "tags": [
      "my_tag"
    ],
    "hidden": false,
    "screenshots": [
      "4103370"
    ]
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "develop"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.keys.modified

Fires when one or more translation keys have been modified in a project though a replace action, a bulk action, or an API call. For example, this event will trigger when you assign or replace key tags for several keys at once.

// project.keys.modified

{
  "event": "project.keys.modified",
  "action": "bulk.add_tags",
  "keys": [
    {      
      "id": 169532683,
      "name": "welcome_header",
      "previous_name": "welcome_header",
      "filenames": {
        "ios": "ios_%LANG_ISO%.strings",
        "android": null,
        "web": "%LANG_ISO%.json",
        "other": null
      },
      "tags": [
        "release_1.1"
      ],
      "hidden": false,
      "screenshots": [
        "4103370"
      ]
    },
    {
      "id": 169685853,
      "name": "feedback_button",
      "previous_name": "feedback_button",
      "filenames": {
        "ios": "ios_%LANG_ISO%.strings",
        "android": null,
        "web": "%LANG_ISO%.json",
        "other": null
      },
      "tags": [
        "release_1.1"
      ],
      "hidden": false
    }
  ],
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "develop"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.keys.deleted

Fires when a translation key has been removed from a project (e.g., deleted individually, through the bulk action, or through the API).

// project.keys.deleted

{
  "event": "project.keys.deleted",
  "action": "lokalise",
  "keys": [
    {
      "id": 16307699,
      "name": "test.title_modified",
      "base_value": "Welcome!",
      "filenames": {
        "ios": "ios_%LANG_ISO%.strings",
        "android": null,
        "web": "%LANG_ISO%.json",
        "other": null
      }
    }
  ],
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "develop"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.key.comment.added

Fires when a new comment has been added for a translation key.

// project.key.comment.added

{
  "event": "project.key.comment.added",
  "comment": {
    "value": "My comment to test.title key"
  },
  "key": {
    "id": 16307701,
    "name": "test.title",
    "filenames": {
      "android": "filename1",
      "ios": "filename2",
      "other": "filename3",
      "web": "filename4"
    }
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.translation.updated

Fires when a translation was modified in a project.

// project.translation.updated

{
  "event": "project.translation.updated",
  "translation": {
    "id": 84835169,
    "value": "Hello, %s!",
    "previous_value": "Hi!",
    "segment": 1
  },
  "language": {
    "id": 640,
    "iso": "en",
    "name": "English"
  },
  "key": {
    "id": 16307701,
    "name": "test.title",
    "filenames": {
    	"ios": null,
      "android": null,
      "web": "%LANG_ISO%.yml",
      "other": null
    }
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.translations.updated

Fires when translations were modified in a project through a bulk action (e.g, translation memory was applied). Each event will include up to a maximum of 300 translations in the payload.

// project.translations.updated

{
    "event": "project.translations.updated",
    "action": "bulk.tm",
    "translations": [
      {
        "id": 84825168,
        "value": "Bonjour!",
        "previous_value": "",
        "language": {
          "id": 673,
          "iso": "fr",
          "name": "French"
        },
        "key": {
          "id": 277,
          "name": "test.welcome"
        }
      },
      {
        "id": 93825168,
        "value": "¡Hola!",
        "previous_value": "",
        "language": {
          "id": 1056,
          "iso": "es",
          "name": "Spanish"
        },
        "key": {
          "id": 277,
          "name": "test.welcome"
        }
      }
    ],
    "project": {
      "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
      "name": "TheApp Project",
      "branch": "master"
    },
    "user": {
      "full_name": "John Doe",
      "email": "[email protected]"
    },
    "created_at": "2023-03-27 13:06:09",
    "created_at_timestamp": 1679915169
}

project.translation.proofread

Fires when a translation has been marked or unmarked as reviewed in a project.

// project.translation.proofread

{
  "event": "project.translation.proofread",
  "translation": {
    "id": 84835169,
    "value": "Hello, %s!",
    "is_proofread": true,
    "segment": 1
  },
  "language": {
    "id": 640,
    "iso": "en",
    "name": "English"
  },
  "key": {
    "id": 16307701,
    "name": "test.title",
    "filenames": {
    	"ios": null,
      "android": null,
      "web": "%LANG_ISO%.yml",
      "other": null
    }
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.translations.proofread

Fires when when multiple translations have been marked or unmarked as reviewed in a project (for example, via an API multicall).

// project.translations.proofread

{
  "event": "project.translations.proofread",
  "action": "api",
  "translations": [
    {
      "id": 1234,
      "value": "Sample text",
      "is_proofread": false,
      "language": {
        "id": 10153,
        "iso": "lv",
        "name": "Latvian"
      },
      "key": {
        "id": 6789,
        "name": "key_1",
        "filenames": {
          "ios": null,
          "android": null,
          "web": "%LANG_ISO%.json",
          "other": null
        }
      }
    },
    {
      "id": 4321,
      "value": "Sample text 2",
      "is_proofread": false,
      "language": {
        "id": 10153,
        "iso": "lv",
        "name": "Latvian"
      },
      "key": {
        "id": 9876,
        "name": "key_2",
        "filenames": {
          "ios": null,
          "android": null,
          "web": "%LANG_ISO%.json",
          "other": null
        }
      }
    }
  ],
  "project": {
    "id": "123456.abcd",
    "name": "Sample project",
    "branch": "master"
  },
  "user": {
    "full_name": "User Name",
    "email": "[email protected]"
  },
  "created_at": "2024-04-24 12:00:26",
  "created_at_timestamp": 1713952826
}

project.contributor.added

Fires when a new contributor was added to a project by invitation of an admin.

// project.contributor.added

{
  "event": "project.contributor.added",
  "contributor": {
    "email": "[email protected]"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.contributor.added_public

Fires when a new contributor added themselves to a project through the public signup link.

The payload is identical to the project.contributor.added (with the only exception being the event field that has the project.contributor.added_public value.

project.contributor.deleted

Fires when a contributor was removed from a project.

// project.contributor.deleted

{
  "event": "project.contributor.deleted",
  "contributor": {
    "email": "[email protected]"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.task.created

Fires when a new translation or review task was created in a project.

// project.task.created

{
  "event": "project.task.created",
  "task": {
    "id": 5022,
    "type": "translation", // supported types are "translation" and "review"  
    "title": "Headings translation",
    "due_date": "2019-08-01 00:00:00",
    "description": "Task description"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.task.queued

Fires when a newly created task has been queued. Please note that a task will be queued when the following conditions are met:

  • This is a review task
  • It has a parent task or a parent translation order
  • Its parent has at least one language that is not yet marked as completed (or a translation order is not marked as completed yet)

The payload is identical to the project.task.created.

project.task.closed

Fires when a task has been marked as closed. Tasks can be closed manually by project admins or automatically upon completion.

// project.task.closed

{
  "event": "project.task.closed",
  "task": {
    "id": 5022,
    "type": "translation", // supported types are "translation" and "review"  
    "title": "Headings translation",
    "due_date": "2019-08-01 00:00:00",
    "description": "Task description"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.task.deleted

Fires when a task has been deleted.

// project.task.deleted

{
  "event": "project.task.deleted",
  "task": {
    "id": 5022,
    "type": "translation",
    "title": "Headings translation",
    "due_date": "2019-08-01 00:00:00",
    "description": "Task description"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.task.language.closed

Fires when a language added to a task has been closed. A language can be closed manually or automatically upon completion.

// project.task.language.closed

{
  "event": "project.task.language.closed",
  "language": {
    "id": 640,
    "iso": "en",
    "name": "English"
  },
  "task": {
    "id": 5022,
    "type": "translation", // supported types are "translation" and "review"  
    "title": "Headings translation",
    "due_date": "2019-08-01 00:00:00",
    "description": "Task description"
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

team.order.created

Fires when a new translation order has been created.

// team.order.created

{
  "event": "team.order.created",
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "develop"
  },
  "order": {
    "id": "20101010D85",
    "provider": "lokalise",
    "currency": "USD",
    "total": 10.00,
    "languages": [
      {
        "id": "1055",
        "iso": "us",
        "name": "English (United States)"
      },
      {
        "id": "597",
        "iso": "ru",
        "name": "Russian"
      }
    ]
  },
  "user": {
    "email": "[email protected]",
    "full_name": "John Doe"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

team.order.deleted

Fires when a translation order has been deleted.

// team.order.deleted

{
  "event": "team.order.deleted",
  "project": {
    "id": "123.abc",
    "name": "Sample project",
    "branch": "master"
  },
  "user": {
    "full_name": "John Doe",
    "email": "[email protected]"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

team.order.completed

Fires when a translation order has been marked as completed.

// team.order.completed

{
  "event": "team.order.completed",
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "order": {
    "id": "20101010D85",
    "provider": "lokalise"
  },
  "created_at": "2019-07-29 12:18:31",
  "created_at_timestamp": 1564395511
}

project.task.initial_tm_leverage.calculated

Fires when an initial translation memory leverage has been calculated for a task. This calculation is performed automatically.

// project.task.initial_tm_leverage.calculated

{
  "event": "project.task.initial_tm_leverage.calculated",
  "task": {
    "id": 12345,
    "title": "New task",
    "description": "Please translate as soon as possible",
    "initial_tm_leverage": {
      "600": {
        "0": 154,
        "50": 5,
        "75": 4,
        "85": 11,
        "95": 0,
        "100%": 6
      },
      "1056": {
        "0": 158,
        "50": 17,
        "75": 0,
        "85": 0,
        "95": 2,
        "100%": 3
      }
    }
  },
  "project": {
    "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",
    "name": "TheApp Project",
    "branch": "master"
  },
  "created_at": "2021-03-30 16:01:11",
  "created_at_timestamp": 1617112871
}

Special fields and events

Replace and bulk actions

Replace and bulk actions may involve many keys or translations at once. The webhook event payload will contain data from 1 and up to 300 objects. If more than 300 objects were involved in the action, you will receive multiple events to capture all the data about the added, modified or removed objects.

Moving and copying keys

When you move or copy keys between projects using the bulk actions the following webhook events will be generated:

  • project.keys.added event will be generated on the destination project if it has a webhook handler subscribed to the key added event.
  • When keys are moved, a project.keys.deleted event will be generated on the source project if it has a webhook handler subscribed to the key removed event.

action field

The action field allows to distinguish what specific user or automated action resulted in the webhook event. Here are the possible values for this field:

api

automation.ai
automation.clear
automation.copy_source
automation.mt
automation.tm
automation.pseudolocalize

bulk.add_tags
bulk.clear
bulk.copy
bulk.copy_source
bulk.delete
bulk.fill
bulk.linked_screenshots
bulk.move
bulk.pseudolocalize
bulk.remove_tags
bulk.tm
bulk.unlinked_screenshots

import.file

replace.tags
replace.translations

linked_screenshots
unlinked_screenshots