Using callbacks to monitor translation progress - TextKing/textking-api GitHub Wiki

You can register callbacks on jobs to be notified about translation status changes.

Register a callback for a job

Request: POST /project/{projectId}/job/{jobId}/callbacks

Registers a callback with the following attributes:

• url: The callback URL.
• trigger_state: The state for which this callback should trigger. One of:
  • translation-pending
  • translation-delivered
  • revision-requested
  • completed
  • canceled
• extra_data (optional): Any string. This will be passed back to the callback URL.

TEXTKING will send a POST request to this callback URL once the job changes to trigger_state. The POST request will contain the following application/x-www-form-urlencoded encoded data:

• project_id: The project ID
• job_id: The job ID
• extra_data: The value passed to extra_data.

Example

Register a callback that will be called when the job state changes to translation-delivered:

POST /project/bc141454-5949-401b-9c05-7591ee2f5624/job/be2bdb76-afe4-4291-bb33-5f3e4019a05e/callbacks HTTP/1.1

Host: api.textking.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer youraccesstoken

{
  "url": "http://example.com/callback-handler",
  "trigger_state": "translation-delivered",
  "extra_data": "String that will be passed back to your callback handler"
}

Response:

HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
Location: https://api.textking.com/v1/project/bc141454-5949-401b-9c05-7591ee2f5624/job/be2bdb76-afe4-4291-bb33-5f3e4019a05e/callback/b48200ac-df99-4f47-ae31-f9a506759ac3
Content-Location: https://api.textking.com/v1/project/bc141454-5949-401b-9c05-7591ee2f5624/job/be2bdb76-afe4-4291-bb33-5f3e4019a05e/callback/b48200ac-df99-4f47-ae31-f9a506759ac3

{
  "id": "b48200ac-df99-4f47-ae31-f9a506759ac3",
  "url": "http://example.com/callback-handler",
  "trigger_state": "translation-delivered",
  "extra_data": {
    "custom_value": "Extra data will be passed back to your callback handler"
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api.textking.com/v1/project/bc141454-5949-401b-9c05-7591ee2f5624/job/be2bdb76-afe4-4291-bb33-5f3e4019a05e/callback/b48200ac-df99-4f47-ae31-f9a506759ac3"
    },
    {
      "rel": "urn:textking:job",
      "href": "https://api.textking.com/v1/project/bc141454-5949-401b-9c05-7591ee2f5624/job/be2bdb76-afe4-4291-bb33-5f3e4019a05e"
    }
  ]
}

Once the translation gets delivered the callback URL will be called as follows:

POST /callback-handler HTTP/1.1

Host: example.com
Content-Type: application/x-www-form-urlencoded

project_id=bc141454-5949-401b-9c05-7591ee2f5624&job_id=be2bdb76-afe4-4291-bb33-5f3e4019a05e&extra_data=String that will be passed back to your callback handler