Callbacks provide an automated way to receive completed translations without polling. Set a callback_url when creating a Translation Request, and we'll send your finished translations directly to your endpoint.

How Callbacks Work

1. Set callback URL when creating your translation request
2. We process your translation request normally
3. Once finished and reviewed, we POST the completed translation to your URL
4. Payload matches what you'd get from a GET request with "finished" status

Important: Translation requests created via file upload do not receive callbacks.

Callback Payload Example

When your translation is complete, you'll receive this JSON payload:

{
  "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"
      }
    ]
  }
}

Benefits

Automated Workflow: Get translations delivered to your system as soon as they're ready without constant polling.

Efficiency: Saves both your server resources and our API from unnecessary requests.

Real-time Updates: Integrate completed translations immediately into your application workflow.

Callback Security

Translation content can significantly impact your application, so securing your callback endpoint is crucial.

Enable HTTPS

Always use HTTPS for your callback endpoint to ensure encrypted communication between our servers and yours.

✅ https://yourapp.com/tolq/callback
❌ http://yourapp.com/tolq/callback

Use Authentication

Include authentication in your callback URL to prevent unauthorized access:

https://yourapp.com/tolq/callback?token=your-secret-token

Verify HMAC Signature

Recommended: Tolq signs each callback with an HMAC SHA-1 signature in the X-Tolq-Signature header using your API key as the signing key.

Example verification (pseudo-code):

expected_signature = hmac_sha1(your_api_key, request_body)
received_signature = request_headers['X-Tolq-Signature']

if expected_signature == received_signature:
    # Request is authentic
    process_callback()
else:
    # Request may be malicious
    reject_request()

Most programming languages provide OpenSSL interfaces for HMAC verification.

IP Whitelisting

If HMAC verification isn't suitable for your setup, you can whitelist our callback IP address:

Tolq Callback IP: 84.22.114.141

All callbacks are proxied through this single IP address for easy whitelisting.

Security Best Practices

1. Keep API credentials secret - never expose them in client-side code
2. Use HTTPS endpoints - encrypt all callback communication
3. Implement authentication - verify callback authenticity
4. Validate signatures - use HMAC verification when possible
5. Whitelist our IP - as an additional security layer

Following these practices ensures your translation workflow remains secure and reliable.