Callbacks

Introduction

In Wordbee, numerous operations are conducted asynchronously.. This implies that when you submit a request, you are provided with an operation identifier (known as a "requestId"). Following this, your request is added to a queue for processing. The execution of your request will commence as soon as sufficient server resources become available. The actual timing of this process can vary, primarily depending on the existing workload on the Wordbee platform at the time of your request. Consequently, there may be varying degrees of delay in the execution of your request. Also see Asynchronous operations

In order to know when such operation is complete, you have two options:

1. You check on the status of the operation using trm/status. This is called “polling” and you would typically wait a few seconds in between checks.

2. You include a callback URL with your request. This URL will be called when the operation is completed. The URL is also triggered when the operation fails.

It goes without saying that option 2 is the more efficient and modern approach.

Specifying a callback URL

Include in JSON BODY

Most asynchronous operations support setting callback URLs in the JSON BODY (if they do the documentation will say so). The parameters are:

{
  "url": "https://callme.com/trigger?ref=1233",
  "headers": [
    { "key": "auth", "value": "ssjj2" }
  ]
}

Include as URL query parameter

Alternatively, it is possible to set the callbackurl as a URL query parameter. We recommend against this option unless the method does not allow to include JSON in the body.

In this case make sure to properly URL-Encode the URL:

../contents/push?callbackurl=http%3A%2F%2Fcallmeback.mycompany.com%3Foperationid%3D22222%26mydata%3Dabcde

Callback execution

When the operation completes with success or failure, the URL is called using HTTP POST and the operation details are included in the JSON body. See Asynchronous operations for the operation result properties.

Example

The method projects/{did}/documents/offline/export (POST) lets you export a file to XLIFF or WORD for offline translation. It is an asynchronous method.

With a callback URL, you would execute the method as follows:

POST /api/projects/{pid}/documents/offline/export?pid=1223
BODY:
{
    documents: [{ "did": 38884, "src": "en", "trg": "es" }],
    format: "Xliff",
    callback: {
        "url": "https://myserver.mycompany.com/callme/offline?reference=223"
    }
}

When the operation completes, the URL is called (using POST) and the operation details are inserted in the body. Example:

{
    "trm": {
        "requestid": 0,
        "isbatch": false,
        "status": "Finished",
        "statusText": "Finished!"
    },
    "custom": {
        "fileref": "ea9c1adeb02f4a9ebe8771583c12fa6b",
        "filename": "export_wm-1180_en_fr.xlf",
        "segments": 10
    }
}

If the operation fails, the URL is called with the operation details:

{
    "trm": {
        "requestid": 559,
        "isbatch": false,
        "status": "Failed",
        "statusText": "Operation failed!",
        "statusInfo": "The parameter xy was not properly supplied"
    }
}

Using Basic Authentication

With the proper headers, callbacks authenticate with your server using the basic authentication protocol. Simply set the “Authorization” header and value. The value is the base-64 encoded credentials string “{username}:{password}”.

POST /api/projects/{pid}/documents/offline/export?pid=1223
BODY:
{
    ...
    callback: {
        "url": "https://myserver.mycompany.com/callme",
        "headers": [
            "key": "Authorization",
            "value": "dXNlcm5hbWU6cGFzc3dvcmQ="
        ]
    }
}