Webhooks 通知外部服务，如聊天客户端或其他外部 API 事件。当特定事件发生时，webhook 可以设置一个 URL。
重要
文件上传仅触发 uploads:create 和 uploads:processing webhook 事件。
keys:create、keys:update、translations:create 和 translations:update webhook 事件不会通过文件上传或自动导入触发：
Webhook 历史记录的保留期为 30 天。
Webhook 响应
Webhook 端点必须在接收到回调后的 5 秒内返回 200–299 范围内的 HTTP 状态代码。其他状态代码和请求超时被视为交付失败。如果交付在 10 个连续事件中失败，webhook 将被停用。回调不会重复。
如果接收到回调，请在 5 秒的请求超时期间内响应。为确保应用程序不会意外触发超时，请在发送 HTTP 响应后再进行处理。
Webhook 请求完整性
每个 webhook 请求都包含一个 X-PhraseApp-Signature 头，该头是使用 webhook 验证令牌作为密钥以及请求中发送的数据生成的。通过计算请求正文的 HMAC 摘要并将其与 X-PhraseApp-Signature 头中的值进行比较来验证请求来源。
示例：
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;
}
每个 webhook 负载的结构在可用的模式文件中定义，文件位于 https://app.phrase.com/webhook_schemas/<event_underscored_name>.json，其中 <event_underscored_name> 对应于带下划线的 webhook 事件名称。
branches:create 可以通过 https://app.phrase.com/webhook_schemas/branches_create.json 访问
|
事件名称 |
说明 |
|---|---|
|
|
一个分支被创建。 |
|
|
一个分支被合并。 |
|
|
对翻译密钥的评论被添加。 |
|
|
多个密钥中的自定义元数据字段值已更新。 |
|
|
在密钥级别更新了自定义元数据字段值。 |
|
|
一个工作被标记为完成。 |
|
|
一个工作被创建。 |
|
|
一个工作的区域被标记为完成。 |
|
|
一个工作的区域被重新打开。 |
|
|
一个工作的区域被审校并标记为完成。 |
|
|
一个工作的区域被审校并重新打开。 |
|
|
一个工作被重新打开。 |
|
|
一个工作已开始。 |
|
|
一个工作被更新。 |
|
|
多个密钥被删除。 |
|
|
已创建一个秘钥。 |
|
|
已删除一个秘钥。 |
|
|
多个秘钥已添加标签。 |
|
|
一个秘钥已添加标签。 |
|
|
一个秘钥已重命名或更改。 |
|
|
在项目中创建了一个新的语言版本。 |
|
|
一个语言版本已删除。 |
|
|
一个语言版本已更改、重命名或重新配置。 |
|
|
一个项目已更改或重新配置。 |
|
|
已创建一个OTA发布。 |
|
|
已删除一个OTA发布。 |
|
|
已创建一个截图。 |
|
|
已删除一个截图。 |
|
|
一个截图已更改或重命名。 |
|
|
一个翻译列表已被删除。 |
|
|
一个翻译列表已被包含。 |
|
|
一个翻译列表已审校。 |
|
|
翻译列表尚未审校。 |
|
|
翻译列表尚未验证。 |
|
|
翻译列表已验证。 |
|
|
某种语言版本中的密钥翻译已添加。 |
|
|
某种语言版本中的密钥翻译由语言服务提供商提供。 |
|
|
某种语言版本中的密钥翻译已被排除。 |
|
|
某种语言版本中的密钥翻译已被包含。 |
|
|
某种语言版本中的密钥翻译已审校。 |
|
|
某种语言版本中的密钥翻译未审校。 |
|
|
某种语言版本中的密钥翻译未验证。 |
|
|
某种语言版本中的密钥翻译已编辑。 |
|
|
某种语言版本中的密钥翻译已验证。 |
|
|
区域文件已成功处理。 |
|
|
区域文件正在处理。 |
要添加一个Webhook，请按照以下步骤操作：
可以从特定 webhook 的菜单中停用 webhook。
要测试 webhook：
使用像RequestBin这样的服务来捕获 webhook 的内容。RequestBin 提供一个 URL，用于收集请求数据以供检查。
每当指定类型的事件发生时，都会向指定的回调 URL 发送一个 POST 请求。请求的 POST 负载是一个 JSON 编码的文档，包含与事件相关的数据。属性event、message和sent_at将始终包含，以及与事件相关的其他属性，如 webhook 被触发的用户、项目和分支。
响应头
发送到回调 URL 的 HTTP 请求将包含几个特殊头。
-
X-PhraseApp-Event:触发 webhook 的事件类型。 -
X-PhraseApp-Signature:使用钩子的秘钥对有效负载进行 HMAC 十六进制摘要。
例如：
Content-Type: application/json
X-PhraseApp-Event: translation:create
X-PhraseApp-Signature: abc123
{
"event": "translations:create",
"message":"Peter translated page.help.title in fr.",
"sent_at":"2015-01-29T09:52:53Z"
"user": {
"id": "abcd1234cdef1234abcd1234cdef1234",
"username": "joe.doe",
"name":"Joe Doe",
"email": "joe@phrase.com",
"position":"首席开发者",
"created_at":"2015-01-28T09:52:53Z",
"updated_at":"2015-01-28T09:52:53Z"
},
"project": {
"id": "abcd1234cdef1234abcd1234cdef1234",
"name":"我的安卓项目",
"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":"我的翻译",
"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"
}
}