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.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.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

Events

project.imported

project.exported

project.copied

project.deleted

project.snapshot

project.branch.added

project.branch.deleted

project.branch.merged

project.languages.added

project.language.removed

project.language.settings_changed

project.key.added

project.keys.added

project.key.modified

project.keys.modified

project.keys.deleted

project.key.comment.added

project.translation.updated

project.translations.updated

project.translation.proofread

project.contributor.added

project.contributor.added_public

project.contributor.deleted

project.task.created

project.task.queued

project.task.closed

project.task.deleted

project.task.language.closed

team.order.created

team.order.deleted

team.order.completed

project.task.initial_tm_leverage.calculated