Callback URLs

When submitting an order for translation, you can set “callback_url” for each job in the order. Gengo will post any updates about the job as they happen which makes it the most efficient way to sync your system with Gengo.

Callback notifications are sent when:

  • A job has been made available to our translators
  • A job has been started by one of our translators
  • A job is ready for review
  • A job has been approved automatically
  • A job is manually approved via our Gengo Dashboard customer interface
  • A job has received a comment by a translator

Gengo will send callbacks every 15 minutes for 12 hours until we receive a 200 status response. If the end point is not reachable, we suggest using the GET /translate/order/{id}/ endpoint to receive the translation.

For file jobs, the request that is sent to your callback will contain a “file_url_tgt” parameter, which is the link to the translated file. This link is different from the url you get from a GET on file jobs in Job(GET), which is “src_file_link”.

Callbacks larger than 60KB cannot be sent. If you are submitting a large text, please break it up into smaller jobs or use the Job(GET) endpoint. We are currently working on a long term solution for this issue.

Callbacks urls can not contain authentication information.

Parameter Formats

Parameters to callbacks are formatted in JSON and submitted with a POST call. For job-related notifications, a Job Payload will be POSTed inside a parameter named “job” as if it were a response. The following is an example of how a client might receive a callback submission for a job from Gengo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
#!/usr/bin/python
# -*- coding: utf-8 -*-

import cgi
import json
form = cgi.FieldStorage()

print("Content-type: text/html\n")

if "job" in form:
    json_data = form["job"].value
else:
    json_data = False

if json_data:
    print(json.loads(json_data, 'utf-8'))
else:
    print("fail")

Comment-related notifications are sent to the same callback when a translator submits a comment for a job. The payload will be in a parameter named “comment”, and will look like this:

job_id : String of the Job ID for which comment applies

body : String of the comment body

ctime : String of the Unix Timestamp for when this comment was submitted

custom_data : String of the custom data associated with the job (if any)

file_url_tgt : String of the full URL of the target file

Here’s an example of how a client might receive a callback submission for a job comment:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
#!/usr/bin/python
# -*- coding: utf-8 -*-

import cgi
import json
form = cgi.FieldStorage()

print("Content-type: text/html\n")

if "comment" in form:
    json_data = form["comment"].value
else:
    json_data = False

if json_data:
    data = json.loads(json_data, 'utf-8')
    comment = {}

    # job id to which comment applies
    comment["job_id"] = data["job_id"]

    # actual comment text
    comment["body"] = data["body"]

    # comment creation time
    comment["ctime"] = data["ctime"]

    # custom data from job (if any)
    custom_data = data["custom_data"] if "custom_data" in data else None

    print(comment)
    print(custom_data)
else:
    print("fail")