Smartling Callbacks

The following documentation covers Smartling callbacks. To learn about Smartling webhooks, which are a specific type of callback, see the Smartling Webhooks Overview.  Although the terms are sometimes used interchangeably, it's important to understand the differences between them. 

• Use callbacks when an API request starts a process that takes time, and you need to be notified once that process is finished. For example, when a source file is uploaded to Smartling via API and you want to be notified when the file upload process has been completed.
• Use webhooks when you want to receive automatic notifications for recurring events in a consistent format. For example, when you want to be notified each time a translation job is completed in a project. 

A callback is a function or endpoint you provide to a system so it can notify you when a specific action is complete. It is usually one-time and tied to a particular request. Callbacks can be used to notify you of certain events. For example, you might ask a system, "Tell me when this task is finished". Once the task is complete, the system sends a callback to your specified URL with the result.

For instance, when you upload a file via API and give a callback URL, Smartling can send an HTTP request, or "callback," to the specified URL once the associated event or action has been completed.

This process is illustrated below:

Callbacks can be used to trigger automated actions in your integration, such as downloading completed translations.

Note: If your Smartling project uses string sharing, publishing one file will trigger callbacks for all files sharing those strings once all strings in a shared file are completed for a locale.

Handling callbacks

To use callbacks, you must make an internet-accessible web server available to receive and handle them. When your callback-handling server receives a valid callback request, it should respond with an HTTP status code in the 2xx range to indicate that the callback was received successfully. If a valid 2xx response is not received, Smartling will retry the callback up to 10 times. See more details on retries below.

Below are some additional recommendations for handling callbacks:

• Consider restricting access to your callback-handling server to the IP addresses of the Smartling callback service (contact Smartling Support for the list of IP addresses).
• Keep the callback handler lightweight to ensure it responds quickly. In other words, avoid putting business logic directly inside the request handler.
• Use HTTPS for improved security.
• Consider using signed requests (see below) to authenticate incoming callback requests.
• Don’t rely solely on callbacks to monitor the status of your translations. Instead supplement them with appropriate status polling.

Testing callbacks

A number of websites, such as https://webhook.site and https://requestbin.com, provide free URLs that can be used to test callbacks. Simply create a URL on one of these sites, then configure your callback to send requests to it. These sites allow you to see the details of the requests sent by the callback service.

In addition, the Ngrok service (https://ngrok.com/) allows you to tunnel callback requests to a non-publicly accessible server, enabling you to test your callback-handling code before making it public.

Callback request structure

Depending on the type of callback, either GET or POST requests may be sent. Below is an example of a GET request URL used with a Files API callback: 

https://webhook.site/1e2d7a5d-94d5-4919-847e-b7bea01693bd?locale=fr-FR&publishStatus=published&fileUri=strings-1-5.txt&ts=1620744030201

Note that the Smartling project ID is not included in this URL. If you need additional information such as the project ID, you can include it as part of the callback URL when configuring the callback.

Below is an example of a POST callback request body from a Jobs API callback:

{
  "type": "job.completed",
  "translationJobUid": "es3yo3lb8ykj",
  "ts": "1644919715512"
}

Below is an example of a POST callback request body from a Strings API callback:

{
  "projectId": "7d964bd0d",
  "hashcode": "7467e4ace11b903446003bb5a7c10e4a",
  "localeId": "fr-FR",
  "type": "string.localeCompleted",
  "publishStatus": "published",
  "translations": [
    {
      "translation": "Un exemple",
      "pluralForm": null,
      "modifiedDate": "2021-05-11T15:20:06Z"
    }
  ],
  "ts": "1620746412599"
}

Additional examples are included below.

You can use the testing websites mentioned above to examine the details of different types of callback requests.

Signed callback requests

Signed callbacks provide greater assurance that incoming callback requests were sent by Smartling and were not tampered with. The process relies on a shared secret held by both the Smartling callback service and your callback handler: Smartling uses the shared secret to generate a signature of the request and includes the signature in a request header; when your callback handler receives the request, it follows the same process using its copy of the shared secret to validate that the result is the same. The process is described in more detail below.

Signing Procedure

Below is the signing procedure for GET requests:

1. Generate a timestamp (in milliseconds since January 1st, 1970 at UTC), and add it as an additional parameter ts in the request URL
2. Generate a raw binary HMAC-SHA1 signature of the full request URL using the shared secret
3. Base64-encode the resulting signature and add it to a request header named X-Smartling-Signature.

Below is the signing procedure for POST requests:

1. Generate a timestamp (in milliseconds since January 1st, 1970 at UTC), and add it as an additional node ts in the request body JSON
2. ‘Flatten’ the JSON structure. For example, for strings-api POST callbacks, this involves moving the contents of the translations node to the top level, changing the key names into the form translations[0].key. See example below.
3. Sort the JSON content alphabetically by key
4. Generate a string from the JSON structure in the form key1=val1|key2=val2|key3=val3
5. Generate a raw binary HMAC-SHA1 signature for this string using the shared secret
6. Base64-encode the resulting signature and add it to a request header named X-Smartling-Signature.

As an example of steps 2, 3, and 4 in the above process, the following POST body:

{
  "projectId": "7d964bd0d",
  "hashcode": "7467e4ace11b903446003bb5a7c10e4a",
  "localeId": "fr-FR",
  "type": "string.localeCompleted",
  "publishStatus": "published",
  "translations": [
    {
      "translation": "Un exemple",
      "pluralForm": null,
      "modifiedDate": "2021-05-11T15:20:06Z"
    }
  ],
  "ts": "1620746412599"
}

is normalized into this string:

hashcode=7467e4ace11b903446003bb5a7c10e4a|localeId=fr-FR|projectId=7d964bd0d|publishStatus=published|translations[0].modifiedDate=2021-05-11T15:20:06Z|translations[0].pluralForm=null|translations[0].translation=Un exemple|ts=1620746412599|type=string.localeCompleted

which is then signed using the shared secret.

Note that the callback testing websites mentioned above sometimes display request parameters in a different order than they were received. This can result in the wrong signature being generated when testing.

Enabling signed requests

Contact your Smartling CSM to enable signed callbacks for your account. You will need to provide a shared secret in the form of a random string of ASCII characters (ideally with length > 12).

Configuring callbacks

Callbacks are configured via API call. For example, when you upload a file for translation, you can pass the URL to be used for the callback sent when the file is translated. The available callbacks, along with the methods of configuration, are listed below:

Files

Jobs

Strings

Issues

Sample callbacks

Below are some examples of callback request GET query strings and POST bodies. You can use the callback testing websites mentioned above to see the exact requests sent for your integration.

File published (GET)

?locale=ru-RU&publishStatus=published&fileUri=example.properties&ts=1542138000086

File prepublished (GET)

?locale=ru-RU&publishStatus=prepublished&fileUri=example.properties&ts=1542138300048

Job completed (GET)

https://callback.handler.com?type=job.completed&translationJobUid=xm5rj2kmxtaj&ts=1644920029445

Job completed (POST)

{
  "type": "job.completed",
  "translationJobUid": "es3yo3lb8ykj",
  "ts": "1644919715512"
}

Job cancelled (GET)

?type=job.cancelled&translationJobUid=vacryeniyvlk

String published (POST)

{
    "projectId": "cef4c4151",
    "hashcode": "493c3a41b5e4648e26f6bbfb94d12341",
    "localeId": "fr-FR",
    "type": "string.localeCompleted",
    "publishStatus":"published",
    "translations": [
        {
            "translation": "bonjour",
            "pluralForm": null,
            "modifiedDate": "2021-03-19T17:32:54Z"
        }
    ]
}

String prepublished (POST)

{
    "projectId": "cef4c4151",
    "hashcode": "493c3a41b5e4648e26f6bbfb94d12341",
    "localeId": "fr-FR",
    "type": "string.localeCompleted",
    "publishStatus": "prepublished",
    "translations": [
        {
            "translation": "bonjour",
            "pluralForm": null,
            "modifiedDate": "2021-03-19T17:32:54Z"
        }
    ]
}

Retries and backoff

Failed deliveries are retried using deterministic exponential backoff, with a total of 10 attempts (including the initial delivery).

Backoff schedule 

The following schedule applies to jobs, files, and strings-related callbacks.

Interval: 60,000ms (60 seconds / 1 minute)