Webhook

Webhooks allow you to receive real-time notifications from Locize when important events occur in your project. This enables automation, integration, and monitoring for your localization workflow.

How to Enable Webhooks

Go to your Locize project Settings.
Select the API, CDN, NOTIFICATIONS tab.
Configure your webhook endpoint URL (must be HTTPS for security).
Save your changes.

Best Practices

Use HTTPS for your webhook endpoint.
Validate incoming requests (e.g., with a secret or signature).
Respond quickly (within 5 seconds) with a 2xx status code.
Log received events for troubleshooting.
If your endpoint fails several times in a row (non-2xx status), Locize will automatically disable the webhook.

Event Types

Event Name	Description
languageAdded	A language was added to the project
languageDeleted	A language was removed from the project
versionAdded	A new version was created
versionDeleted	A version was deleted
referenceLanguageChanged	The reference language was changed
orderCreated	A translation order was created
orderCompleted	A translation order was completed
invitationAccepted	A user accepted an invitation to join the project
versionPublished	A version was published
versionOverwrote	A version was overwritten
languageOverwrote	A language was overwritten
namespaceAdded	A namespace was added
namespaceDeleted	A namespace was deleted
namespaceUpdated	A namespace was updated
namespaceCompleted	A namespace translation was completed
namespaceNotCompletedAnymore	A fully translated namespace received new untranslated segments (sent per language)

Get directly notified on a webhook url if something noticeable happens.

To enable this service go to settings, select the services tab and configure your endpoint. Make sure you have a secure https endpoint.

The following messages will be sent as json payload with a POST request.

All messages will have the following structure:

{
   "id":"830fbcbb-90b7-4f0f-86bb-c82b55aab385", // the message id
   "name":"dummyTestEvent", // the message name
   "occurredAt":"2018-01-02T20:05:59.008Z", // the moment when this message occurred in ISO 8601 format
   "message":"William Timberland just added a webhook to THIS PROJECT!", // a descriptive text of this message
   "payload":{ // a variable payload
      "messageTypes":[
         "languageAdded",
         "languageDeleted",
         "versionAdded",
         "versionDeleted",
         "referenceLanguageChanged",
         "orderCreated",
         "orderCompleted",
         "invitationAccepted",
         "versionPublished",
         "versionOverwrote",
         "languageOverwrote",
         "namespaceAdded",
         "namespaceDeleted",
         "namespaceCompleted",
         "namespaceNotCompletedAnymore"
      ]
   },
   "meta":{ // a meta object containing...
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6", // the project id
         "name":"THIS PROJECT", // the project name
         "slug":"albo6dxk" // the project slug
      },
      "user":{ // if message issued by a user
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a", // the user id
         "firstname":"William", // the user firstname
         "lastname":"Timberland" // the user lastname
      },
      "link":"https://www.locize.app/p/albo6dxk/v/latest" // a link pointing to the locize client
   }
}

Warning: If the request to your endpoint fails several times in a row (status code not equal to 2xx), the webhook service is disabled automatically.

Example Events

languageAdded

Triggered when a new language is added to the project.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"languageAdded",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"William Timberland added language de!",
   "payload":{
      "language":"de"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "user":{
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a",
         "firstname":"William",
         "lastname":"Timberland"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/latest"
   }
}

languageDeleted

Triggered when a language is removed.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"languageDeleted",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"William Timberland removed language de!",
   "payload":{
      "language":"de"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "user":{
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a",
         "firstname":"William",
         "lastname":"Timberland"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/latest"
   }
}

versionAdded

Triggered when a new version is created.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"versionAdded",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"William Timberland added version prod!",
   "payload":{
      "version":"prod"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "user":{
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a",
         "firstname":"William",
         "lastname":"Timberland"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/latest"
   }
}

versionDeleted

Triggered when a version is deleted.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"versionDeleted",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"William Timberland removed version prod!",
   "payload":{
      "version":"prod"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "user":{
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a",
         "firstname":"William",
         "lastname":"Timberland"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/latest"
   }
}

referenceLanguageChanged

Triggered when the reference language changes.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"referenceLanguageChanged",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"William Timberland changed reference language from en to de!",
   "payload":{
      "from":"en",
      "to":"de"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "user":{
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a",
         "firstname":"William",
         "lastname":"Timberland"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/latest"
   }
}

orderCreated

Triggered when a translation order is created.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"orderCreated",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"William Timberland created a translation order with gengo!",
   "payload":{
      "service":"gengo",
      "version":"latest"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "user":{
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a",
         "firstname":"William",
         "lastname":"Timberland"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/latest"
   }
}

orderCompleted

Triggered when a translation order is completed.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"orderCompleted",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"gengo order completed!",
   "payload":{
      "service":"gengo",
      "version":"latest"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "link":"https://www.locize.app/p/albo6dxk/orders"
   }
}

invitationAccepted

Triggered when a user accepts an invitation.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"invitationAccepted",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"William Timberland accepted the invitation and is now part of your project!",
   "payload":{},
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "user":{
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a",
         "firstname":"William",
         "lastname":"Timberland"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/latest"
   }
}

versionPublished

Triggered when a version is published.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"versionPublished",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"William Timberland published version prod!",
   "payload":{
      "version":"prod"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "user":{
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a",
         "firstname":"William",
         "lastname":"Timberland"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/prod"
   }
}

The versionPublished event will not be triggered when auto publish is enabled. For reacting to new translations, consider namespaceNotCompletedAnymore and namespaceCompleted.

versionOverwrote

Triggered when a version is overwritten.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"versionOverwrote",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"William Timberland overwrote version prod with test!",
   "payload":{
      "from":"test",
      "to":"prod"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "user":{
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a",
         "firstname":"William",
         "lastname":"Timberland"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/prod"
   }
}

languageOverwrote

Triggered when a language is overwritten.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"languageOverwrote",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"William Timberland overwrote language en version in version prod with test!",
   "payload":{
      "from":"test",
      "to":"prod",
      "language":"en"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "user":{
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a",
         "firstname":"William",
         "lastname":"Timberland"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/prod"
   }
}

namespaceAdded

Triggered when a namespace is added.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"namespaceAdded",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"William Timberland added namespace landingpage in version latest!",
   "payload":{
      "namespace":"landingpage",
      "version":"latest"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "user":{
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a",
         "firstname":"William",
         "lastname":"Timberland"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/latest"
   }
}

namespaceDeleted

Triggered when a namespace is deleted.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"namespaceDeleted",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"William Timberland removed namespace landingpage in version latest!",
   "payload":{
      "namespace":"landingpage",
      "version":"latest"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "user":{
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a",
         "firstname":"William",
         "lastname":"Timberland"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/latest"
   }
}

namespaceUpdated

Triggered when a namespace is updated.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"namespaceUpdated",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"William Timberland updated namespace for language en landingpage in version latest!",
   "payload":{
      "namespace":"landingpage",
      "language":"en",
      "version":"latest"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "user":{
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a",
         "firstname":"William",
         "lastname":"Timberland"
      },
      "link":"https://www.locize.app/cat/albo6dxk/v/latest/en/landingpage"
   }
}

namespaceCompleted

Triggered when a namespace translation is completed.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"namespaceCompleted",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"Translation of namespace landingpage in language en for version latest completed!",
   "payload":{
      "namespace":"landingpage",
      "language":"en",
      "version":"latest"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/latest/en/landingpage"
   }
}

namespaceNotCompletedAnymore

Triggered when new segments in a namespace need translation: a namespace that was 100 % translated in a language dropped below 100 %, typically because new keys were added. It is sent once per language and namespace for that transition, not for every new key.

{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"namespaceNotCompletedAnymore",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"New segments of namespace landingpage ready to be translated in language en for version latest!",
   "payload":{
      "namespace":"landingpage",
      "language":"en",
      "version":"latest"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/latest/en/landingpage"
   }
}

Not covered by this event: a change of the source text of an existing key. The translation still exists, so the namespace stays "completed"; the editor flags such segments as issue 302 and a translation order picks them up with "Include if source value changed after target value". With Automatic Translation enabled the event is rarely sent, because new keys are already translated when the statistics are recalculated; use namespaceUpdated, orderCreated and orderCompleted for automations in that setup.