Callbacks (with asynchronous operations)

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:

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.
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:

callbackurl

The callback URL. It may contain query parameters. The URL is called with HTTP POST.

string?, Optional

callback

Permits to specify both a URL and HTTP headers.

url : include the URL to be triggered
headers : Optional array to set header key and value pairs.

Example:

CODE

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

object?, Optional

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.

Example:

CODE

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

Notes:

Please URL-Encode the callback URL. Tool to encode URLs: https://www.urlencoder.org/
If you need to set HTTP headers then please set the callback in the payload JSON BODY.

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:

CODE

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:

CODE

{
    "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:

CODE

{
    "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}”.

CODE

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

Testing callbacks the easy way

Several free services exist to simplify testing callbacks and web hooks.

Our preferred free service is: https://webhook.site/

It gives you a unique callback URL that you can provide as callbacks to Wordbee asynchronous operations.

When the URL is then called by Wordbee, the web page shows full details of payload and headers transmitted by Wordbee.