Some events in Smartling can trigger callbacks to a specified URL. Callbacks let you know when an action is completed. For example, a file or string is translated in a particular locale or a translation job is complete.
The callback service also offers the option to sign requests. This ensures that the payload of the request was not tampered with and was actually sent by Smartling.
Callbacks are issued from IP 126.96.36.199. To make sure you receive necessary callbacks, you should whitelist this IP address.
If a callback fails, Smartling will make multiple attempts to reach the designated URL. However, we do not keep retrying a failed callback indefinitely. Try to make sure your callback URL is as stable as possible and be aware that callbacks are not a 100% reliable way of being notified that a file is published. If the upload has begun but is taking more than a minute to complete, it responds with a 202 status.
String is translated for a locale: This callback is sent to the URL provided in the Create strings request. It can be sent as a GET or POST request. However, only the POST request includes translations.
The POST request looks like this:
The GET request includes the same information - with the exception of the
translations object as querystring parameters:
Type of Callback Received
Below are the types of callbacks received for different job entities (jobs, strings, files). To receive callbacks for pre-published strings or files, contact your Customer Success Manager to have it enabled at a site-level.
Jobs: A job callback is sent when a job is completed, cancelled, or a locale of the job is completed.
- Job completed: The callback will contain:
- Job cancelled: The callback will contain the
- String completed: The callback will be sent when the string is completed for a locale. It will contain the hashcode,
- Pre-published: The callback will be sent when the string is prePublished for a locale. The callback will contain: hashcode,
- Pre-published: The callback will contain “locale”, status, fileUri, and ts. For example:
- Published: The callback will contain “locale”, status, fileUri, and ts. For example:
Set Up Sign Requests
You can enable sign requests as a way of ensuring that the request is actually coming directly from Smartling, and hasn't been intercepted or tampered in any way.
To enable this option, Smartling needs a 'secretKey' from you. Contact our support team. There will be a single
secretKey key per account. Smartling will store this key, along with the
accountUid, in the callback service.
Smartling allows GET and POST methods for requesting a callback. Basically, the request body (or URL) is the message to be signed by your
secretKey via HMAC-SHA1, and then base64 encoded. This signature is then added to a request header called
X-Smartling-Signature for you to validate. The specifics are outlined below.
For all signed requests, a timestamp parameter (
ts) will be added to all requests. It will be milliseconds from epoch (January 1st, 1970 at UTC).
GET: When using a GET request, all parameters will be appended to the callback URL. The callback URL is the message to be signed.
https://www.callback.com/event | secretKey: SECRET-KEY
A jobs callback will have
localeId as parameters. The callback that will be sent to you will be: https://www.callback.com/event?translationJobUid=1qazxsw23edc&localeId=es-ES&ts=436363636332 Smartling takes this URL and signs it via HMAC-SHA1 using your secretKey:
signature = base64.encode(hmac("SHA1", "https://www.callback.com/event?translationJobUid=1qazxsw23edc&localeId=es-ES&ts=436363636332",SECRET-KEY));
From your end, you can perform the same procedure and compare results with the value in the
X-Smartling-Signature header. If they are the same, then this is a valid request.
When using POST, we will create a request body (JSON) with the custom parameters sent in the request. We will append all parameters (in alphabetical order) with a pipe delimiter ("|") to create the message to be signed.
callback URL: https://www.callback.com/event
A jobs callback will have
The callback that will be sent to the client will be:
https://www.callback.com/event with a JSON request body such as:
Smartling will alphabetize the parameter names and concatenate them (with a pipe delimiter) to create a string as our message. It will look something like this:
signature = base64.encode(hmac("SHA1", "localeId=es-ES|translationJobUid=1qazxsw23edc|ts=436363636332",SECRET-KEY));
From your end, you will follow the same procedure and compare your signature to the value of X-Smartling-Signature. If they are the same, then this is a valid request.
For nested objects, we will flatten the structure and follow the same procedure as above.
The parameters to create the signature will be as follows:
Once we've flattened the object, we will add the timestamp (
ts) parameter and proceed with the general Secret Creation as documented above.
Ready to use the Smartling APIs? Click here.