webhook 会将事件通知给聊天客户端或其他外部 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 事件名称。
|
事件名称 |
说明 |
|---|---|
|
|
分支已创建。 |
|
|
分支已合并。 |
|
|
已添加翻译键的备注。 |
|
|
自定义元数据字段值已在多个键中更新。 |
|
|
自定义元数据字段值已在键级别更新。 |
|
|
工作已被标记为完成。 |
|
|
工作已创建。 |
|
|
工作的区域已被标记为完成。 |
|
|
工作的区域已被重新打开。 |
|
|
工作的区域已审校并标记为完成。 |
|
|
工作的区域已审校并重新打开。 |
|
|
工作已被重新打开。 |
|
|
工作已开始。 |
|
|
工作已更新。 |
|
|
多个键已被删除。 |
|
|
已创建键。 |
|
|
已删除键。 |
|
|
已向多个键添加标记。 |
|
|
已向键添加标记。 |
|
|
已重命名或更改键。 |
|
|
已在项目中创建新的语言版本。 |
|
|
已删除语言版本。 |
|
|
已更改、重命名或重新配置语言版本。 |
|
|
已更改或重新配置项目。 |
|
|
已创建 OTA 版本。 |
|
|
已删除 OTA 版本。 |
|
|
已创建屏幕截图。 |
|
|
已删除屏幕截图。 |
|
|
已更改或重命名屏幕截图。 |
|
|
已删除翻译列表。 |
|
|
已包含翻译列表。 |
|
|
已审校翻译列表。 |
|
|
翻译列表已取消审校。 |
|
|
翻译列表已设为未验证。 |
|
|
翻译列表已设为已验证。 |
|
|
已添加特定语言版本中某个键的翻译。 |
|
|
特定语言版本中某个键的翻译已由语言服务商交付。 |
|
|
特定语言版本中某个键的翻译已被排除。 |
|
|
特定语言版本中某个键的翻译已被包含。 |
|
|
特定语言版本中某个键的翻译已审校。 |
|
|
特定语言版本中某个键的翻译未审校。 |
|
|
特定语言版本中某个键的翻译未验证。 |
|
|
特定语言版本中某个键的翻译已编辑。 |
|
|
特定语言版本中某个键的翻译已验证。 |
|
|
区域文件已成功处理。 |
|
|
区域文件正在处理中。 |
要添加 webhook，请按照以下步骤操作：
-
在 页面中，向下滚动至 并点击 Configure。
页面随即打开。
-
点击 添加 webhook。
窗口随即打开。
-
提供 webhook 详细信息。
-
可选：。
-
点击保存。指定的 webhook 已添加到 页面上的列表。
可以从特定 webhook 的 菜单中停用 webhook。
要测试 webhook：
使用 RequestBin 等服务来捕获 webhook 的内容。RequestBin 提供了一个 URL，用于收集请求数据以供检查。
每当发生指定类型的事件时，都会向指定的 callback URL 发送 POST 请求。请求的 POST 有效负载是一个 JSON 编码的文档，其中包含有关该事件的相关数据。属性 event、message 和 sent_at 将始终包含在内，以及与事件相关的其他属性，例如触发 webhook 的 user、project 和 branch。
响应头
向 callback URL 发出的 HTTP 请求将包含几个特殊的头信息。
-
X-PhraseApp-Event：触发 webhook 的事件类型。 -
X-PhraseApp-Signature：有效负载的 HMAC 十六进制摘要，使用 hook 的密钥作为键。
例如：
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": "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"
}
}