Phrase API

Webhooks (TMS)

Webhooks are arbitrary URLs which handle HTTP POST requests allowing the notification of 3rd-party systems about specified events.

Phrase monitors if a webhook callback was successfully received. If a webhook reception fails 3000 times, it is deactivated with a notification sent to Administrators of the account and the failure is noted on the specific webhook on the Webhooks page. The retry mechanism has a maximum of 10 retries with the interval between retries being computed up to a maximum value of 30 minutes.

Webhooks can be disabled/enabled, tested, or deleted from the webhooks page by hovering over individual webhooks and clicking ellipses.png to access the menu. The History function provides an overview of calls over the previous 14 days and failed webhooks can be replayed.

Important

White-listing Webhook connections by IP addresses was deprecated and has been replaced by Webhook security tokens.

Webhooks can be selected for the following events:

  • Job status changed

  • Job created

  • Job assigned

  • Job due date changed

  • Job source updated

  • Job target updated

  • Continuous Job updated

  • Project created

  • Project status changed

  • Project due date changed

  • Project template created

  • Project template changed

  • Project template deleted

  • Shared project assigned

  • Project metadata updated

  • Pre-translation finished

  • Analysis created

  • Job deleted

  • Project deleted

  • Job exported

  • Job unexported

Configure Webhooks

To configure Webhooks, follow these steps:

  1. From the Settings Setup_gear.png page, scroll down to the Integrations section and click on Webhooks.

    The Webhooks page opens.

  2. Click Add webhook.

    The creation page opens.

  3. Provide URL.

  4. Provide security token if required.

    Specify a value to be added as a x-phrase-token header which can be used to authenticate the sender of the webhook.

  5. Select events.

  6. Click Preview schema to view the webhook response when running.

  7. Click Create webhook.

    The webhook is added to the list on the Webhooks page.

Webhook Usage Examples

A website called RequestBin will provide a URL to used when creating a webhook.

The next time a Job Status is changed or a Job is created in the account, the URL receives the appropriate response from the system. Actual usage can be more complex and the receiving of the response should be considered a signal for the connected application to perform certain actions.

Events

Examples of a job status change, a job assignment, job creation and when a job's due date is changed.

Job status has changed

{
"jobParts": [
  {
    "id": 9,
    "uid": "ipmdz5p0sagqcOYaijTZU2",
    "internalId": "4",
    "task": "SEfSaenvqFgctE1I0_dc1",
    "fileName": "en.txt",
    "targetLang": "af",
    "workflowLevel": 1,
    "status": "NEW",
    "wordsCount": 2,
    "beginIndex": 0,
    "endIndex": 1,
    "isParentJobSplit": false,
    "dateDue": null,
    "dateCreated": "2016-11-02T17:06:54Z",
    "project": {
      "id": 2,
      "uid": "4RvyVbwX00KerkomA7kpT9",
      "lastWorkflowLevel": 1
    },
    "assignedTo": [
      {
        "vendor": {
          "id": 1,
          "name": "Abc",
          "vendorToken": "4-ifos0-CAqPo"
        }
      },
      {
        "linguist": {
          "id": 3,
          "firstName": "Admin",
          "lastName": "Admin",
          "userName": "admin",
          "email": "admin@example.com",
          "role": "ADMIN",
          "timezone": "Europe/London",
          "active": true,
          "deleted": false,
          "terminologist": false,
          "dateCreated": "2016-10-11T07:43:22Z"
        }
      }
    ]
  }
],
"event": "JOB_STATUS_CHANGED"
}

Job Assigned

{
"jobParts": [
  {
    "id": 9,
    "uid": "ipmdz5p0sagqcOYaijTZU2",
    "internalId": "4",
    "task": "SEfSaenvqFgctE1I0_dc1",
    "fileName": "en.txt",
    "targetLang": "af",
    "workflowLevel": 1,
    "status": "NEW",
    "wordsCount": 2,
    "beginIndex": 0,
    "endIndex": 1,
    "isParentJobSplit": false,
    "dateDue": null,
    "dateCreated": "2016-11-02T17:06:54Z",
    "project": {
      "id": 2
      "uid": "4RvyVbwX00KerkomA7kpT9",
      "lastWorkflowLevel": 1
    },
    "assignedTo": [
      {
        "vendor": {
          "id": 1,
          "name": "Abc",
          "vendorToken": "4-ifos0-CAqPo"
        }
      },
      {
        "linguist": {
          "id": 3,
          "firstName": "Admin",
          "lastName": "Admin",
          "userName": "admin",
          "email": "admin@example.com",
          "role": "ADMIN",
          "timezone": "Europe/London",
          "active": true,
          "deleted": false,
          "terminologist": false,
          "dateCreated": "2016-10-11T07:43:22Z"
        }
      }
    ]
  }
],
"event": "JOB_ASSIGNED"
}

Job Created

{
 "jobParts": [
   {
     "id": 9,
     "uid": "ipmdz5p0sagqcOYaijTZU2",
     "internalId": "4",
     "task": "SEfSaenvqFgctE1I0_dc1",
     "fileName": "en.txt",
     "targetLang": "af",
     "workflowLevel": 1,
     "status": "NEW",
     "wordsCount": 2,
     "beginIndex": 0,
     "endIndex": 1,
     "isParentJobSplit": false,
     "dateDue": null,
     "dateCreated": "2016-11-02T17:06:54Z",
     "project": {
       "id": 2,
       "uid": "4RvyVbwX00KerkomA7kpT9",
       "lastWorkflowLevel": 1
     },
     "assignedTo": [
       {
         "vendor": {
           "id": 1,
           "name": "Abc",
           "vendorToken": "4-ifos0-CAqPo"
         }
       },
       {
         "linguist": {
           "id": 3,
           "firstName": "Admin",
           "lastName": "Admin",
           "userName": "admin",
           "email": "admin@example.com",
           "role": "ADMIN",
           "timezone": "Europe/London",
           "active": true,
           "deleted": false,
           "terminologist": false,
           "dateCreated": "2016-10-11T07:43:22Z"
         }
       }
     ]
   }
 ],
 "event": "JOB_CREATED"
}

Job Due Date Changed

{
  "jobParts": [
    {
      "id": 127865777,
      "uid": "ElTXvXnNIHEN2xgL5sU2L2",
      "internalId": "1",
      "task": "LvkAHilgobApeoVm_dc4",
      "fileName": "EU White Paper Edited.doc",
      "targetLang": "de",
      "workflowLevel": 1,
      "status": "NEW",
      "wordsCount": 204,
      "beginIndex": 0,
      "endIndex": 16,
      "isParentJobSplit": false,
      "dateDue": "2018-09-11T22:00:00Z",
      "dateCreated": "2018-09-10T06:25:41Z",
      "project": {
        "id": 12277756,
        "uid": "4RvyVbwX00KerkomA7kpT9
        "lastWorkflowLevel": 1
      },
      "assignedTo": []
    }
  ],
  "event": "JOB_DUE_DATE_CHANGED"
}

Status Table

When working with APIs, Webhooks and the UI, the status may be named slightly differently.

Rest API

Webhook

UI

NEW

NEW

NEW

ACCEPTED

ASSIGNED

ACCEPTED (by provider)

DECLINED

DECLINED_BY_LINGUIST

DECLINED (by provider)

REJECTED

REJECTED_BY_LINGUIST

REJECTED (by provider)

DELIVERED

COMPLETED

DELIVERED

EMAILED

EMAILED

EMAILED (by provider)

COMPLETED

COMPLETED_BY_LINGUIST

COMPLETED (by provider)

CANCELLED

CANCELLED

CANCELLED

Was this article helpful?

Sorry about that! In what way was it not helpful?

The article didn’t address my problem.
I couldn’t understand the article.
The feature doesn’t do what I need.
Other reason.

Note that feedback is provided anonymously so we aren't able to reply to questions.
If you'd like to ask a question, submit a request to our Support team.
Thank you for your feedback.