Callbacks

Tolq allows you setting a callback_url when you are creating a Translation Request. That url will be queried via a POST once the translations are finished and reviewed by our servers with a payload equivalent to the one you would get from a GET request on a Translation Request with the same status. Translation requests created via uploading a file will not receive these callbacks.

{
  "id": 7,
  "name": null,
  "slug": "untitled-7",
  "context_url": null,
  "description": null,
  "created_at": "2016-03-02T10:23:32.441Z",
  "completed_at": "2016-03-02T10:23:32.638Z",
  "quality": "machine",
  "target_language_code": "tq",
  "style_guide_reference_id": 1,
  "status": "finished",
  "orders": [
    {
      "quality": "machine",
      "target_language_code": "tq",
      "status": "finished",
      "ordered_words": 22,
      "price": 0.0,
      "total_words": 22
    }
  ],
  "original": {
    "title": "The example",
    "intro": "An example on how to use Tolq",
    "body": "Tolq is a platform that allows you to easily translate lots of content"
  },
  "translations": {
    "tq": {
      "title": "Arcu pretium",
      "intro": "Et ultricies ex elit ut ante Vitae",
      "body": "Augue ut a consectetur magna lacus enim ac euismod elementum morbi eu lobortis"
    }
  },
  "total_orders": 1,
  "total_ordered_words": 22,
  "total_words": 22,
  "total_cost": 0.0,
  "total_keys": 3,
  "callback_response_code": null,
  "last_callback_at": null,
  "_links": {
    "review": [
      {
        "target_language_code": "tq",
        "target_language_name": "Tolq Latin",
        "href": "https://clients.tolq.com/api/7/review/tq"
      }
    ]
  }
}

With callbacks, you don't need to constantly poll for the state of a translation request. You will get the approved translations in your system as soon as possible. This automated workflow can save you and us a lot of time.

Callback Security

Translations and copy can have severe impact on your application. Therefore we advise clients to take extra care when using callbacks. It should go without saying that you should keep your api details secret.

Prevent listening in

Prevent listening in by enabling https on the callback endpoint. This allows us to set up an encrypted connection.

Use authentication on your callback url

Provide a token or authentication details in the callback url, such that the endpoint cannot be accessed by unauthorised users.

Verify our requests with our HMAC signature

Tolq signs each callback in the X-Tolq-Signature header with an HMAC using a sha1. The signature uses your api key as the signing key. Most, if not all, common programming languages provide an interface to OpenSSL to do the verification. This way, you can ensure that the request originates from Tolq.

IP Whitelisting

We understand that verifying the HMAC signature is not applicable in every scenario. Therefore, we proxy all our callbacks, allowing you to whitelist a single ip address. This address is 84.22.114.141.