Callbacks and Webhooks
Some events in Smartling can trigger callbacks to a specified URL after a webhook has been configured. Callbacks notify you when an action is completed. For example, a file or string is translated in a particular locale or a translation job is complete.
Our callback service offers the option to sign requests to ensure that the payload of the request was not tampered with and was actually sent by Smartling.
Callbacks are issued from IP 22.214.171.124. To make sure you receive 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 query string parameters:
The following table describes the types of callbacks Smartling offers: jobs, strings, files, and issues. To receive callbacks for pre-published strings or files, contact your Customer Success Manager to have them enabled at a site level.
|Job||Job Completed||A job is completed, or completed for a locale.|
|Job Cancelled||A job has been cancelled|
|String||String Prepublished||A string has been prepublished for a locale. For more information on prepublishing, see Prepublish Translations.|
|String Published||A string has been published for a locale.|
|File||File Prepublished||A file has been prepublished for a locale.|
|File Published||A file has been published for a locale.|
|Issue||Issue Created||An issue has been created.|
|Issue Deleted||An issue has been deleted.|
|Issue State Changed||An issue has been opened or resolved.|
|Issue Answered||An issue has been answered.|
|Issue Severity Level Changed||An issue’s severity level has been changed to Low, Medium, or High.|
|Issue Comment Added||A comment has been added to an issue. Includes the comment body, creation date, and commenter.|
|Issue Watcher Added||A watcher has been added to an issue.|
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. 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) is 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:
Smartling takes this URL and signs it via HMAC-SHA1 using your secretKey. For example:
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, for example:
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.