Callbacks: a tool to get localization project alerts

At POEditor, we are comitted to find the best ways to achieve localization automation for our users.

To make devs’ lives easy, we thought it would be nice to offer a way to trigger an external link on particular events. As usual, our users’ feedback weighed heavily in deciding to add this new feature. So without further ado, we give you POEditor callbacks.

What are callbacks and why use them

Callbacks are simple way to get notications about specific events in POEditor localization projects. They can be set up by the project owner and admins.

They are a good way to save resources, because you no longer need to poll the API at certain intervals. When the events are triggered, POEditor fires a request to a specific URL you set for that event.

How to set up and track callbacks

Setting up a callback is easy. You need to access Integrations > Callbacks. Here, choose a localization project and the event that should trigger the callback, then add the web address you want fired when the event is triggered.

Currently there are three events you can choose:
• Language Completed
• Language Proofread (which requires Proofreading to be enabled in Project Settings )
• New Terms

To protect the endpoint, it is possible to also add a secret to the calls. The call will have a “X-Callback-Secret” header added with that value.

After you set your callback, you can send a test to your endpoint:

{
    "event": {
        "name": "test"
    }
}

The JSON payload examples we send for each event:

{
    "event": {
        "name": "language.completed"
    },
    "project": {
        "id": ******,
        "name": "Load data #2",
        "public": 0,
        "open": 0,
        "created": "2019-05-17T10:31:50+0000"
    },
    "language": {
        "name": "German",
        "code": "de"
    },
    "stats": {
        "strings": {
            "translated": 3,
            "fuzzy": 0,
            "proofread": 0
        }
    }
}

{
    "event": {
        "name": "language.proofread"
    },
    "project": {
        "id": ******,
        "name": "Android localization",
        "public": 1,
        "open": 0,
        "created": "2015-08-13T09:39:32+0000"
    },
    "language": {
        "name": "English",
        "code": "en"
    }
}

{
    "event": {
        "name": "new_terms.added"
    },
    "project": {
        "id": ******,
        "name": "Android localization",
        "public": 1,
        "open": 0,
        "created": "2015-08-13T09:39:32+0000"
    }
}

You can track your callbacks activity with your callbacks log. The log is available for the last the last 10 days.

Observations

The data is sent via POST and the JSON is put in a payload parameter.

Keep in mind that we listen for a response with HTTP status code 200 when we send the callback only for a short time (30 seconds at this point). If we don’t get a reply, a timeout error is generated after this,

Also, please make sure you don’t do all your processing on that endpoint and create a separate process for it. If we don’t get a 200 HTTP code when we fire the callback we try again 2 more times. After that we stop trying.