Webhook

Webhook 是一种当 TikTok 平台内发生特定事件时触发的自动化 HTTP 回调，会将实时通知发送到您设置的回调 地址。采用此机制后，您可不必再持续使用 API 轮询来获取相关异步事件的信息，TikTok 会主动将事件数据发送到您的系统，且一旦相关事件数据生成就立即发送。这些通知以 JSON 格式通过 HTTPS POST 传递到您为开发者应用配置的回调 URL。您可以使用这些实时信息来更新您的系统或作为特定的业务流程的触发条件，确保您的应用程序与 TikTok 事件高效且及时地保持同步。

Webhook 回调 URL

若要接收 Webhook 消息，您需要为开发者应用注册 Webhook 回调 URL。若想为您的开发者应用配置回调 URL，可使用 Webhook API 接口 /business/webhook/update/。

回调 URL 必须满足以下要求： - 即时响应 HTTP 200 状态码，以确认收到事件通知。 - 回调 URL 接口必须使用 HTTPS 协议。

若未返回 HTTP 200状态码，TikTok 会认为此次发送不成功。TikTok 将在 72 小时内使用指数退避算法再次尝试发送事件通知。72 小时后，TikTok 将忽略并停止发送此通知。

TikTok 尽力保证 Webhook “至少成功发送一次”。Webhook 接口可能会多次收到同一个事件。您可以将事件作幂等处理，避免重复接收事件。

Webhook 结构

请求 Header

这些重要的 Header 可用于记录 Webhook 验证、问题报告和故障排查信息。下表仅列出了部分请求的 Header。

| 字段{20%} | 类型{15%} | 描述{65%} |
|---|---|---|
| tiktok-signature | string | TikTok Webhook 随签名一起发送，目标服务器可使用此签名验证相关事件来自 TikTok，而非第三方或恶意系统。请查看 [Webhook 验证](https://ads.tiktok.com/marketing_api/docs?id=1759978341579777)章节了解详情。 |
| webhook-schema-version | string | Webhook 请求 Body 的结构版本。<br>当前版本为 v1.0。 |
| x-tt-logid | string | Webhook 请求的唯一标识符。请确保记录此标识符，以便故障排查。 <br>示例：202201120803530102451591650189C78。|

请求 Body

webhook-schema-version: 1.0

| 字段{20%} | 类型{15%} | 描述{65%} |
|---|---|---|
| client_key | string | TikTok API for Business 开发者门户网站为您的应用提供的应用 ID。此应用 ID 可在开发者门户网站中<strong>应用管理</strong>下找到：<br>示例：`bwo1m23456a7k89` |
| event | string | 事件类型名称。<br>示例：`post.publish.complete` |
| create_time | integer | 事件发生的时间，为以秒为单位的 UTC 时间。<br>示例：`1615338610` |
| user_openid | string | TikTok 账户的应用唯一识别ID，即通过[/tt_user/oauth2/token/](1738084387220481.html)接口获得的 `open_id` 字段，且作为所有 TikTok 账号 API 请求中的 `business_id` 参数使用。 <br>示例：`_000abPL1cJIdVefgDhGijkl2mFn3AB0abY4`|
| content | string | 事件信息的序列化 JSON 字符串。<br> 示例: `&#123;\"share_id\":\"v_pub_url~v1.2345123456789123456\", \"reason\":\"video_format_check_failed\"&#125;` |

client_key、event、create_time、user_openid 和 content是 Webhook 发送各种请求时常用的字段。content 字段中的内容因事件而异，因此每个事件的说明仅包含 content 内的字段（您可以假设其他所有字段均与上表所述一致）。