Webhooks
Webhooks are a very common tool to keep different systems in sync. Use webhooks to receive instant notifications about events happening in Lokalise as HTTP POST requests.
Setting up webhooks
To set up the Webhooks app for your project through the UI:
- Navigate to Apps.
- Find Webhooks in the list, click on it, and then press Install.
- Enter the URL where events will be sent.
- Define the HTTP header, if you need to.
- Select the events that you want to subscribe to.
- Click Enable app (or Save changes if you're adding new handlers).
Alternatively, you can subscribe and unsubscribe from webhooks programmatically using our API. Find more information and try out the API on our playground.
Requirements
The webhook is sent once an event happens and it expects a response from your endpoint, configured on the URL parameter.
- Your service must accept HTTP POST requests.
- Your service must return a
2xx
status code (200, 201, 202, etc.) upon receiving a notification, including the initialping
that is sent when a new webhook handler is configured.
You can check the Webhook sample apps to learn how to listen to webhook events in third-party apps, and handle the incoming notifications.
Origin IP addresses
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
HTTP headers
Special HTTP headers are sent with every notification for security purposes. By checking the header values, your service endpoint can validate that the request is coming from Lokalise and not a malicious source.
Identifiers
All events include the following HTTP headers:
Project-Id
: The Lokalise project id.Webhook-Id
: The webhook handler id (check the Webhooks API if you'd like to use it).
Here's an example:
{
"HTTP_X_SECRET"=>"7d32ea041f77c0b9126da8c0dc2cd3b469893314",
"HTTP_PROJECT_ID"=>"963054665b7c313dd9b323.35886655",
"HTTP_WEBHOOK_ID"=>"03e2f534ba11de6eef20264c16ef4e4146c5cba1",
"HTTP_X_EVENT"=>"project.translation.updated"
}
Secrets
By default, a webhook secret is generated for you automatically once the app is enabled. The secret is represented as a random alphanumeric string and is sent inside an X-Secret
header. This secret can be regenerated at any time. To do that, open Apps > Webhooks, find the desired webhook and click on the Refresh icon:

You can also enter any other value for this header in the text input.
Moreover, you can also choose to send not the X-Secret
header but X-Api-Key
: in this case you'll need to provide a value for this header as well.
Custom header
Alternatively to the secrets, you can choose to send a custom header by selecting the corresponding radio box:

In this case you'll need to enter the header's name (we recommend to use an X-
prefix) and its value.
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.
Webhook events
You can subscribe to the following events for each project:
- Translation updated, reviewed
- File uploaded, downloaded
- Project deleted, copied
- Snapshot created
- Key added, removed, modified
- Key comment added
- Task created, queued, closed, deleted, language closed, initial TM leverage calculated
- Language added, removed, settings changed
- Contributor added, removed
- Order created, completed, deleted
- Branch added, removed, merged
Please refer to the event details and payload examples to learn more.
File uploads
When you upload a translation file to a Lokalise project, you can utilize webhook events to learn what data has been added or modified. You'll need to enable the following events: project.keys.added
, project.keys.modified
, and project.translations.updated
.
These additional events allow you to spare further queries to the Lokalise AP. 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.
Bulk and replace actions
Lokalise webhooks support certain bulk actions and find/replace actions.
Please note that as the bulk action may involve many keys, the event payload will contain data from 1 and up to 300 keys. If more than 300 keys were involved in the bulk action, you will receive multiple events to capture all the data about the added and removed keys.
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.
Deleting keys
When you delete keys through the bulk action, a project.keys.deleted
webhook event will be generated if the project is subscribed to the key removed event.
Assigning tags
When you assign or replace keys tags, the project.keys.modified
event will be fired.
Updating translations
When you perform a find/replace operation, apply translation memory to keys through a bulk action, a project.translations.updated
webhook event will be generated if the project is subscribed to the translation updated event.
The webhook payload will also include an action field to state which particular action caused the data changes (e.g., bulk.pseudolocalize
).
Receiving webhooks: examples
Please find sample apps that listen to Lokalise webhooks in the corresponding section.
Updated 4 days ago