Getting Started With Smartling APIs

Callbacks

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 184.73.255.141. To make sure you receive necessary callbacks, you should whitelist this IP address.

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:

{
   "projectId": "51df0cf05",
   "hashcode": "3325fc569a651bef02a93732e48701b4",
   "localeId": "fr-FR",
   "type": "string.localeCompleted",
   "translations": [
      {
         "translation": "Bonjour!",
         "pluralForm": null,
         "modifiedDate": "2016-12-01T14:18:00Z"
      }
   ]
}

The GET request includes the same information - with the exception of the translations object as querystring parameters: ?projectID=9db9036e6 etc.

Type of Callback Received

Types of callbacks received for different job entities (jobs, strings, files):

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 the translationJobUid, type=job.completed
  • Job cancelled: The callback will contain the translationJobUid, type=job.cancelled, ts

Strings: String completed: For now, a callback will only be sent when the string is completed for a locale. Additional types may be added down the road. The callback will contain the hashcode, projectId, localeId and a type=string.localeCompleted.

Files: The callback will contain fileUri and "locale" (Note, this is locale, not localeId).

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.

Signing Procedure

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.

Example:
callback URL: https://www.callback.com/event | secretKey: SECRET-KEY

A jobs callback will have translationJobUid and 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:

Example:
signature = base64.encode(hmac("SHA1", "https://www.callback.com/event?translationJobUid=1qazxsw23edc&localeId=es-ES&ts=436363636332",SECRET-KEY));
...
request.addHeader("X-Smartling-Signature",signature);
// end

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.

POST
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.

Example:
callback URL: https://www.callback.com/event
secretKey: SECRET-KEY

A jobs callback will have translationJobUid and localeId as parameters.

The callback that will be sent to the client will be:
https://www.callback.com/event with a JSON request body such as:

{
     "translationJobUid":"1qazxsw23edc",
     "localeId": "es-ES",
     "ts": 436363636332
}

Secret Creation

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:

localeId=es-ES|translationJobUid=1qazxsw23edc|ts=436363636332

(pseudo code)

signature = base64.encode(hmac("SHA1", "localeId=es-ES|translationJobUid=1qazxsw23edc|ts=436363636332",SECRET-KEY));
...
request.addHeader("X-Smartling-Signature",signature);
// end

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.

Nested Objects

For nested objects, we will flatten the structure and follow the same procedure as above.

Example response:

{
    "projectId":"abcdef",
    "hashcode":"abcdefghijkl",
    "localeId":"fr-FR",
    "translations":[{
        "translation":"some translation",
        "pluralForm":"OTHER",
        "modifiedDate":"2015-11-21T01:51:17Z"
    }],
    "type":"string.localeCompleted"
}

The parameters to create the signature will be as follows:

  • projectId=abcdef
  • hashcode=abcdefghijkl
  • localeId=fr-FR
  • translations[0].translation=some translation
  • translations[0].pluralForm=OTHER
  • translations[0].modifiedDate=2015-11-21T01:51:17Z
  • type=string.localeCompleted

Once we've flattened the object, we will add the timestamp (ts) parameter and proceed with the general Secret Creation as documented above.

Was this article helpful?