Webhooks notify external services such as chat clients or other external APIs of events. A webhook can set a URL when a specific event takes place.
File uploads only trigger the uploads:create
and uploads:processing
webhook events.
Webhook response
A 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 receiving a callback, respond within the 5-second request timeout period. To ensure applications don’t accidentally trigger a timeout, defer processing until after the HTTP response has been sent.
Webhook request integrity
Each webhook request includes an X-PhraseApp-Signature
header which is generated using the webhook verification token as a secret along with the data sent in the request. Verify that a request origin by computing the HMAC digest of the request body and comparing it to the value in the X-PhraseApp-Signature
header.
Examples:
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; }
Event name |
Description |
---|---|
|
A new language version was created in a project. |
|
A language version was changed, renamed or reconfigured. |
|
A language version was deleted. |
|
A locale file was uploaded. |
|
A locale file was processed. |
|
A key was created. |
|
A key was renamed or changed. |
|
A key was deleted. |
|
Multiple keys were deleted. |
|
A translation of a key in a certain language version was added. |
|
A translation of a key in a certain language version was edited. |
|
A translation of a key in a certain language version was delivered by a language service provider. |
|
A translation of a key in a certain language version was reviewed. |
|
A translation of a key in a certain language version was unreviewed. |
|
A comment on a translation key was added. |
|
A job was started. |
|
A job was marked as complete. |
|
A job was reopened. |
|
A locale of a job was marked as completed. |
|
A locale of a job was reopened. |
|
A locale of a job was reviewed and marked as complete. |
|
A locale of a job was reviewed and reopened. |
|
A screenshot was created. |
|
A screenshot was changed or renamed. |
|
A screenshot was deleted. |
|
A branch was created. |
|
A branch was merged. |
|
An OTA release has been created. |
|
An OTA release has been deleted. |
To add a webhook, follow these steps:
-
From the Configure.
page, scroll down to and clickThe
page opens. -
Click Add webhook.
The
window opens. -
Provide webhook details.
-
Optionally
. -
Click Save. The specified webhook is added the list on the
page.
A webhook can be deactivated from the
menu of a specific webhook.To test a webhook:
-
From the Send Test-Notification from the menu.
page, select a webhooks and selectA notice is presented indicated the test was successful.
Use a service such as RequestBin to capture the contents of a webhook. RequestBin provides a URL that collects request data for inspection.
A POST request is sent 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 such as the user, project and branch the webhook was triggered from.
Reponse headers
HTTP requests made to the 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.
Example:
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" } }
Slack is a platform for centralized team communication. Slack offers integrations that automatically pulls information and activity from outside tools into Slack in a way that’s timely, relevant and searchable.
If not using the Slack plugin, webhooks can be manually setup to provide integration.
To integrate notifications generated by a webhook into a Slack channel, set up an incoming webhook within Slack to obtain a webhook URL. This webhook URL can be set it as the callback URL for a webhook.
A POST request is sent 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 a specified channel.
Example payload:
{ "text": "Andre has updated a translation in project: 'my project'", "username": "PhraseApp" }