APIs

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 184.73.255.141. 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:

{
   "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 query string parameters: ?projectID=9db9036e6 etc.

Callback Types

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.

Callback Type Event Description
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.

Signing Procedure

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.

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. For 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, for 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

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

Ready to use the Smartling APIs? Click here.

Was this article helpful?