Webhooks

Use webhooks to receive instant notifications about events happening in Lokalise as HTTP POST requests.

The webhook is sent once an event happens and it expects a response from your service with a 2xx status code. We do not sign the requests, so you may want to restrict the incoming requests from the following IPs:

  • 159.69.72.82
  • 94.130.129.39
  • 195.201.158.210
  • 94.130.129.237
  • 195.201.84.53
  • 18.192.113.205
  • 3.67.82.138

To set up the app for your project:

  1. Navigate to Apps.
  2. Find Webhooks in the list, click on it, and then press Install.
  3. Enter configuration parameters: URL to send events to and the branch (if the branching feature is enabled for your project).
  4. Select the desired events.
  5. Click Enable app.

Webhook secret

Webhook secret is generated for you automatically once the app is enabled. The secret is represented as a random alphanumeric string:

The secret is sent to the specified webhook with each request. By checking the secret's value you can make sure the request is not coming from a malicious source.

The secret can be regenerated at any time. To do that, open Apps > Webhooks, find the desired webhook and click on the Refresh icon (check the screenshot above).

Changes

We've completely rewritten webhook implementation. Projects with the old webhook system will have a Legacy Webhooks app which is documented here.

What's new in the updated version:

  • You can subscribe and unsubscribe from webhooks programmatically, using our API.
  • Retry mechanism (see below).
  • Secret is sent in header, so you can validate the request.
  • Payload for some events has been updated.

Requirements

Your service must:

  • Accept HTTP POST requests
  • Return 2xx status code (200, 201, 202 etc.) upon receiving a notification

Retry mechanism

In case a webhook handler failed to receive the notification, our system will try to re-send it up to 24 hours:

  • after ± 1 minute, after the first failure.
  • after ± 5 minutes, after the second failure.
  • after ± 10 minutes, after the third failure.
  • after ± 20 minutes, after the fourth failure.
  • after ± 30 minutes, after the fifth failure.
  • every hour up to 24 hours.

We do our best to preserve the order of webhooks, though it is not guaranteed. All events will continue to accumulate for up to 24 hours if the webhook handler is not responding.

After 24 hours all accumulated events will be deleted and the webhook handler disabled. A disabled webhook handler must be re-enabled manually in the project settings.

Please note that if your application fails to process the webhook notification in 8 seconds (in other words, it does not respond with a 2xx status code), we'll consider the request to be unsuccessful and will try to re-send it as explained above.

Available webhook events

  • project.imported
  • project.exported
  • 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.key.modified
  • project.keys.deleted
  • project.key.comment.added
  • project.translation.updated
  • project.translation.proofread
  • project.contributor.added
  • project.contributor.deleted
  • project.task.created
  • project.task.closed
  • project.task.deleted
  • project.task.language.closed
  • project.task.initial_tm_leverage.calculated
  • team.order.created
  • team.order.completed
  • team.order.deleted

Webhook payload examples

project.imported

// project.imported:

{  
  "event": "project.imported",  
  "import": {  
    "filename": "en.json",  
    "format": "json",  
    "inserted": 231,  
    "updated": 0,  
    "skipped": 0  
  },  
  "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.exported:
{
  "event": "project.exported",
  "export": {
    "type": "json",
    "filename": "files/export/138c1ffa0ad94848f01f980e7f2f2af19d1bd553/67d1a7ff9cab3a57e32ea71c4561a58d/locales.zip",
    "platform": "Web"
  },
  "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.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:

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

{  
  "event": "project.branch.added",  
  "project": {  
    "id": "123.abc",  
    "name": "Sample Project",  
  },  
  "branch": {  
    "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:

{  
  "event": "project.branch.deleted",  
  "project": {  
    "id": "123.abc",  
    "name": "Sample Project",  
  },  
  "branch": {  
    "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:

{  
  "event": "project.branch.merged",  
  "project": {  
    "id": "123.abc",  
    "name": "Sample Project",  
  },  
  "branch": {  
    "name": "develop",  
  },  
  "target_branch": {  
    "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:

{  
  "event": "project.languages.added",  
  "languages": [  
    {  
      "id": 734,  
      "iso": "it",  
      "name": "Italian"  
    }  
  ],  
  "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.language.removed:

{  
  "event": "project.language.removed",  
  "language": {  
    "id": 734,  
    "iso": "it",  
    "name": "Italian"  
  },  
  "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.language.settings_changed:

{  
  "event": "project.language.settings_changed",  
  "language": {  
    "id": 734,  
    "iso": "it",  
    "name": "Italian"  
  },  
  "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.key.added:

{  
  "event": "project.key.added",  
  "key": {  
    "id": 16307699,  
    "name": "test.title",  
    "base_value": "Hello, world!"  
  },  
  "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.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  
    }  
  },  
  "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.keys.deleted:

{  
  "event": "project.keys.deleted",  
  "keys": [  
    {  
      "id": 16307699,  
      "name": "test.title_modified",  
      "filenames": {  
        "ios": "ios_%LANG_ISO%.strings"  
      }  
    },  
    {  
      "id": 16307700,  
      "name": "test.to_delete"  
    }  
  ],  
  "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.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"  
  },  
  "user": {  
    "email": "[email protected]",  
    "full_name": "John Doe"  
  },  
  "created_at": "2019-07-29 12:18:31",  
  "created_at_timestamp": 1564395511  
}


// project.translation.updated:

{  
  "event": "project.translation.updated",  
  "translation": {  
    "id": 84835169,  
    "value": "Hello, %s!",  
    "previous_value": "Hi!"  
  },  
  "language": {  
    "id": 640,  
    "iso": "en",  
    "name": "English"  
  },  
  "key": {  
    "id": 16307701,  
    "name": "test.title"  
  },  
  "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.translation.proofread:

{  
  "event": "project.translation.proofread",  
  "translation": {  
    "id": 84835169,  
    "value": "Hello, %s!",  
    "is_proofread": true  
  },  
  "language": {  
    "id": 640,  
    "iso": "en",  
    "name": "English"  
  },  
  "key": {  
    "id": 16307701,  
    "name": "test.title"  
  },  
  "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:

{  
  "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.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:

{  
  "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"  
  },  
  "user": {  
    "email": "[email protected]",  
    "full_name": "John Doe"  
  },  
  "created_at": "2019-07-29 12:18:31",  
  "created_at_timestamp": 1564395511  
}


// 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"  
  },  
  "user": {  
    "email": "[email protected]",  
    "full_name": "John Doe"  
  },  
  "created_at": "2019-07-29 12:18:31",  
  "created_at_timestamp": 1564395511  
}


// project.task.deleted:

{  
  "event": "project.task.deleted",  
  "task": {  
    "id": 5022,  
    "title": "Headings translation",  
    "due_date": "2019-08-01 00:00:00",  
    "description": "Task description"  
  },  
  "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.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"  
  },  
  "user": {  
    "email": "[email protected]",  
    "full_name": "John Doe"  
  },  
  "created_at": "2019-07-29 12:18:31",  
  "created_at_timestamp": 1564395511  
}


// team.order.created:

{  
    "event": "team.order.created",  
    "project": {  
        "id": "138c1ffa0ad94848f01f980e7f2f2af19d1bd553",  
        "name": "TheApp Project"  
    },  
    "order": {  
        "id": "20101010D85",  
        "provider": "lokalise",  
        "currency": "USD",  
        "total": 10.00  
    },  
    "user": {  
        "email": "[email protected]",  
        "full_name": "John Doe"  
    },  
    "created_at": "2019-07-29 12:18:31",  
    "created_at_timestamp": 1564395511  
}


// team.order.deleted:

{  
  "event": "team.order.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  
}


// team.order.completed:

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


// 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  
}

Receiving webhooks (example in PHP)

<?php
$input = @file_get_contents("php://input");  
$data = json_decode($input, true);  
http_res

Did this page help you?