About webhooks

You can use webhooks to notify external services, like chat clients or other external APIs, of events that happened in Phrase.

A webhook is a mechanism for notifying external services, like chat clients, project management tools and other external APIs, of events that happened in Phrase. You can use a webhook to set a URL for Phrase to call whenever a certain event takes place.

You can create webhooks for the following kinds of events:

Event	Description	Notes
locales:create	A new language version was created in a project
locales:update	A language version was changed, renamed or reconfigured
locales:delete	A language version was deleted
uploads:create	A locale file was uploaded	Sends notifications on successful uploads
uploads:processing	A locale file was processed	Sends notifications on uploads that were created, but not completed yet.
keys:create	A key was created
keys:update	A key was renamed or changed (e.g. description added/removed)	Adding a tag to a key does not trigger the event
keys:delete	A key was deleted
keys:batch_delete	Multiple keys were deleted
translations:create	A translation of a key in a certain language version was added
translations:update	A translation of a key in a certain language version was edited
translations:deliver	A translation of a key in a certain language version was delivered by a language service provider
translations:review	A translation of a key in a certain language version was reviewed
comments:create	A comment on a translation key was added
jobs:start	A job was started
jobs:complete	A job was marked as complete
jobs:reopened	A job was reopened
jobs:locale:complete	A locale of a job was marked as completed
jobs:locale:reopened	A locale of a job was reopened
jobs:locale:review:complete	A locale of a job was reviewed and marked as complete
jobs:locale:review:reopen	A locale of a job was reviewed and reopened
screenshots:create	A screenshot was created
screenshots:update	A screenshot was changed or renamed
screenshots:delete	A screenshot was deleted
branches:create	A branch was created
branches:merge	A branch was merged

Add a webhook

To add a webhooks from the Translation Center, follow these steps:

1. Go to the Integrations page.
2. In the entry for webhooks, click Configure. Then, click Add Webhook.
3. Choose the project you want to add a webhook to from the menu.
4. Enter the URL that Phrase should call each time an event occurs.
5. (Optional) You can provide a secret, which will be used to generate the HMAC signature for webhook requests. Leave it empty to use the default webhook secret for this project, which you can view through the Default webhook secret link on the overview.
6. Choose one or more event types from the menu.
7. Type a description to remember what the webhook is for.
8. Select whether or not the webhook should also be triggered for events from branches 
9. Click Save.

Test a webhook

You can test a webhook to make sure the endpoint receives the event notification. To test a webhook, choose More > Send Test Notification. Phrase will send a test notification to the callback URL you provided.

One way to capture the contents of a webhook is to use a service like RequestBin. RequestBin gives you a URL that collects requests made to it, so you can easily inspect their contents.

See the webhook history

You can access the webhook history by clicking on a specified webhook. On the webhook history page you can see an overview of the webhook setting and a report of all successful and failed webhook deliveries. 

Via show details you can see and examine each webhook event. To better understand failed deliveries you can examine request and response payloads, as well as any potential exceptions. Once debugged you can send the webhook again. Phrase stores webhook deliveries for 30 days, so you can examine them within this timeframe. 

Use data from webhooks

Phrase sends a POST request to the specified callback URL each time an event of the specified type occurs. The request’s POST payload is a JSON-encoded document with relevant data for the event. The attributes event and message will always be included, along with additional attributes relevant to the event, like the user and projectand the branch the webhook was triggered from.

Response headers

HTTP requests made to your callback URL will contain several special headers.

• X-PhraseApp-Event: The type of event that triggered the webhook.
• X-PhraseApp-Signature: The HMAC hex digest of the payload, using the hook's secret as the key.

Content-Type: application/json
X-PhraseApp-Event: translation:create
X-PhraseApp-Signature: abc123

{
  "event": "translations:create",
  "message": "Peter translated page.help.title in fr.",
  "user": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe",
    "email": "joe@phrase.com",
    "position": "Lead Developer",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  "project": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Android Project",
    "main_format": "xml",
    "project_image_url": "http://assets.phrase.com/project.png",
    "account": "account",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  "branch": {
  "name": "branch_name"
  },
  "translation": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "content": "My translation",
    "unverified": false,
    "excluded": false,
    "plural_suffix": "",
    "key": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "home.index.headline",
      "plural": false
    },
    "locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "de",
      "code": "de-DE"
    },
    "placeholders": [
      "%{count}"
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
}

Respond to a webhook

Your webhook endpoint must return an HTTP status code in the 200–299 range within 5 seconds of receiving a callback. Other status codes and request timeouts are considered to be delivery failures. A webhook will be deactivated if delivery fails for more than 10 consecutive events. Callbacks are not repeated.

If you’re receiving a callback, the most important thing to do is to respond within the 5-second request timeout period. To make sure that apps don’t accidentally trigger a timeout, try defering processing until after the HTTP response has been sent.

Verify the integrity of a webhook request

Each webhook request includes an X-PhraseApp-Signature header which is generated using your webhook's verification token as a secret, along with the data sent in the request. You can verify that a request originated from Phrase by computing the HMAC digest of the request body and comparing it to the value in the X-PhraseApp-Signature header.

Example Code

 Ruby

def verify_webhook(signatureheader)
  digest = OpenSSL::Digest::Digest.new('sha256')
  hmac = OpenSSL::HMAC.digest(digest, VERIFICATION_TOKEN, request.body)
  hmac = Base64.encode64(hmac).strip
  hmac == signatureheader
end

 PHP 

function verify_webhook($signatureheader){
  $hmac = hash_hmac('sha256', $requestBody, $verificationToken, true);
  $hmac = trim(base64_encode($hash));
  return $hmac == $signatureheader;
}

Use webhooks for Slack integration

Slack is a platform for centralized team communication. Slack offers integrations that let you automatically pull information and activity from outside tools into Slack in a way that’s timely, relevant and searchable.

To integrate notifications generated by a Phrase webhook into a Slack channel, you’ll need to set up an incoming webhook within Slack to obtain a webhook URL. To do so, follow these instructions from Slack. Once you have your webhook URL, you can set it as the callback URL for a webhook in Phrase.

Phrase sends a POST request to the provided URL each time an event of the specified type occurs. The request’s POST payload is a JSON-encoded document with relevant data that Slack can use to display a short description of the event in the channel of your choice.

Example Payload

{
  "text": "Andre has updated a translation in project: 'my project'",
  "username": "PhraseApp"
}

Deactivate a webhook

To deactivate an existing webhook without deleting it, choose More > Deactivate Webhook.

FAQs

Will file uploads trigger webhook events for resources that were modified/created by the upload (e.g. translations:update or keys:create)?

No, as it stands, file uploads will only trigger the webhook events uploads:create and uploads:processing.