How callbacks work in the system
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
- Set callback URL when creating your translation request
- We process your translation request normally
- Once finished and reviewed, we POST the completed translation to your URL
- 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
- Keep API credentials secret - never expose them in client-side code
- Use HTTPS endpoints - encrypt all callback communication
- Implement authentication - verify callback authenticity
- Validate signatures - use HMAC verification when possible
- Whitelist our IP - as an additional security layer
Following these practices ensures your translation workflow remains secure and reliable.