Notify your own HTTP endpoints about translation changes
This option is for self-hosting your own endpoint which reacts to changes in your translation project.
See Notification payloads for an overview of the JSON your endpoint will receive.
Adding a Web Hook
- Open the developer tools modal from any project view where you see the :wrench icon:
- Switch to the "Hooks" tab, and click the "New Hook" link
- Choose "Web Hook", enter your URL, and confirm with "Add hook".
Web Hook settings:
URL:
Enter the full URL to your endpoint. We will POST notifications to this over HTTP.Secret:
You can't edit this field, but you'll need it if you plan to verify incoming requests.Headers:
You can add custom HTTP headers here. (e.g. for authentication), but you can't override our user-agent, or our signature header.Other options are common to all notification services.
Responding to Loco
Please respond with status 200 (or any 2xx code) when you receive a notification. Any other status code (including redirects) will put your hook into an error state.
When this happens, Loco will delay future notifications and may eventually stop sending to your endpoint.
If you plan to react to a hook by pulling translations from our API, please do so asynchronously, or at least very quickly. Requests that take a long time to respond may result in timeout, and this will be treated as an error condition.
Verifying notifications
Your web hook configuration includes a secret which is a random string of text known only to you and Loco. You can copy this from the Loco interface.
When posting a JSON payload to your endpoint, we sign the raw request body using a hash-based message authentication code (HMAC) with SHA-256. The payload also includes the Unix timestamp (in seconds) at the time the request was compiled. A simple example payload would be signed as follows (in pseudo code):
hash_hmac('sha256', '{"time":1757947511}', 'Very Secret text')
The signature is then added to the request in a header as follows:
X-Loco-Signature-256: 6c19f92f3b9a0b455f1a911ac74cd2f926d058b51057ad646cb50e1e0e510e2d
You can verify the request is legitimate by computing the signature yourself and comparing it to this header. You may also want to reject any requests that have not been timestamped within a very short time window.