Using notification callbacks

How to use callbacks to get notifications when the status of a document or project changes in Smartcat

You can use callbacks to get notifications when the status of a document or project changes in Smartcat, and to get the status of importing bilingual XLIFF versions of documents.

Configuration for receiving callbacks

In order to get notification callbacks, you need to follow these steps:

1. Configure the web server.
2. Configure the callback URL for WebAPI. 
3. Configure notifications using the API methods described below.
4. Process the callback request when a project's status changes. URL: <callbackURL>/project/status

   Request structure:

   POST /api/callback/project/status HTTP/1.1
   Host: example.local
   Content-Type: application/json
   ["1e2d703f-9def-4d27-ab4d-350cbbe8c44b", "b5bf9123-31b3-4e45-9ee9-8c14d15a4145"]

5. Process the callback request when a document's status changes.

   URL: <callbackURL>/document/status

   Request structure:

   POST /api/callback/document/status HTTP/1.1 
   Host: example.local 
   Content-Type: application/json 
   ["189_25", "310_25"]

6. Process the callback request to finish importing a translation from an XLIFF.

   URL: <callbackURL>/document/translationImportCompleted

   Request structure:

   POST /api/callbackUrl/document/translationImportCompleted HTTP/1.1 
   Host: example.local 
   Content-Type: application/json 
   ["60606_25", "61234_25"]

If some of the notifications from the queue were sent but some could not be delivered, the undelivered notifications are put in the retry queue.

Interval for resending notifications if Smartcat cannot access the callback URL:
30-second delay with 8 attempts; the delay doubles for each subsequent attempt.

Callback API methods

Creating or updating settings for receiving notifications

First of all, you need to specify the address of your server that will receive the callback requests.

You can do this via POST: /api/integration/v1/callback

Request body:

{
"url": "smartcat.stage-next.sc.local:8012/api/receiver/myTest",
"additionalHeaders": [
    {
    name: "Authorization",
    value: "Basic ZG0eMTpRd3VydHkdMjM="
    }
  ]
}

This example specifies the callback URL that notifications will be sent to, as well as the additionalHeaders parameter, which adds an HTTP header to the notifications. This HTTP header can be useful if the web server is behind a firewall and authentication is necessary. If this is not the case, you can ignore the additionalHeaders parameter.

You can use this method either to set a new callback URL or to change the existing one.

Request structure:

POST /api/integration/v1/callback HTTP/1.1
Host: smartcat.stage-next.sc.local
Authorization: Basic ZG0eMTpRd3VydHkdMjM=
Content-Type: application/json
Cache-Control: no-cache
{
"url": "http://myurl.net:8012/api/receiver/myTest",
"additionalHeaders": [
    {
    name: "Authorization",
    value: "Basic ZG0eMTpRd3VydHkdMjM="
    }
  ]
}

The HTTP status code 200 is returned if settings were updated successfully.

The HTTP status code 400 is returned in the following cases:

• Invalid URI. One of the headers has a value that is empty, null, or consists only of spaces.
• One of the headers is set to null.

Deleting settings for receiving notifications

To remove the settings for receiving notifications, use DELETE: /api/integration/v1/callback

Request structure:

DELETE /api/integration/v1/callback HTTP/1.1
Host: smartcat.stage-next.sc.local
Authorization: Basic ZG0wMTpRd2VydHkxMjM=
Cache-Control: no-cache

After the request is executed, the HTTP status code 204 is returned if the notification settings were deleted.

Reading the account settings for receiving notifications

To view the current notification settings, use

GET: /api/integration/v1/callback

Request structure:

GET /api/integration/v1/callback HTTP/1.1
Host: smartcat.stage-next.sc.local
Authorization: Basic ZG0eMTpRd3VydHkdMjM=
Cache-Control: no-cache

Response structure:

{
  "url": "string",
  "additionalHeaders": [
    {
    "name": "string",
    "value": "string"
  }
 ]
}

The HTTP status code 200 is returned if the request was completed successfully.

The HTTP status code 404 is returned if the notification settings are not set.

Reading recent delivery errors

If errors occurred when executing a callback request, you can view them via GET: /api/integration/v1/callback/lastErrors

You can specify the limit parameter for this method to restrict the number of errors shown. For example: https://smartcat.stage-next.sc.local/api/integration/v1/callback/lastErrors?limit=100

Request structure:

GET /api/integration/v1/callback/lastErrors HTTP/1.1
Host: smartcat.stage-next.als.local
Authorization: Basic ZG0eMTpRd3VydHkdMjM=
Cache-Control: no-cache

Response structure:

[
{
"Id": "string",
"Created": "2017-02-01T00:38:39.062Z",
"Expired": "2017-02-01T00:38:39.062Z",
"ApplicationId": "string",
"Url": "string",
"FailResponse": {
  "Reason": "string",
  "Code": 0,
  "Content": "string"
  }
 }
]

The Id parameter contains the identifier for the description.

The Reason parameter contains a description of the reason for the error (e.g., timeout, unknown host or an invalid certificate).

The Code parameter contains the response code returned by the web server.

The Content parameter contains the error text returned by the web server. 

The HTTP status code 200 is returned if the request was executed successfully.

The HTTP status code 400 is returned when the specified limit exceeds the maximum.

If the callback requests were executed without errors, an empty array is returned.