Knowledge Base

Documentation to help you use the POEditor localization platform effectively

How to use callbacks

Owner Admin

Callbacks are available starting with the Premium plan.

Callbacks are a tool developed for you to get notified of specific events in POEditor localization projects.

These notifications help you save resources by avoiding polling the API at certain intervals.

Callbacks can be set up by the project owner and admins, as well as by organization managers (if the project is hosted on an organization).

How callbacks work

When the events are triggered, POEditor fires a request to a specific web address you set for that event.

Callbacks (Integrations page) - POEditor localization platform

To set up a callback, go to Integrations > Callbacks. Then select a project and your desired event and add the URL you want fired when the event is triggered.

You can also add a secret to the calls if you want to protect the endpoint. The call will have a “X-Callback-Secret” header set with that value.

The events supported for callbacks at this time are:

  • Language completed (for when a language reaches 100% completion rate)
  • Language proofread (for when a language reaches 100% completion rate and is also 100% proofread; requires Proofreading to be enabled in the project's Settings
  • New terms added (manually, file import, API, integrations)

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

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

Examples

Below are JSON payload examples we send for each event.

For the language completed event, you will receive infromation regarding the project (id, name, whether it's public or open source, creation date), the completed language (name and code) and some stats about this language (number of translations in language, number of fuzzy translations, number of proofread translations).

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

For the language proofread event, you will receive infromation regarding the project (id, name, whether it's public or open source, creation date) and the completed language (name and code).

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

For the new terms added event, you will receive infromation regarding the project (id, name, whether it's public or open source, creation date).

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

How the data is sent

The data is sent via POST, having a Content-Type header with the value application/x-www-form-urlencoded. The JSON is put in a payload parameter.

Note that we listen for a response with HTTP status code 200 when we send the callback only for a little while (30 seconds at this point). After that a timeout error is generated.

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 give up.

Logs

You can check your callbacks activity in the last 10 days in your callbacks log.

Additional help

Related articles