创建或更新 TikTok 账号 Webhook 配置
您可以使用本接口创建或更新开发者应用层级与您的 TikTok 账号活动相关的 Webhook 事件配置。
若想了解如何创建这些 Webhook 事件配置，请查看通过 Webhook API 订阅 TikTok 账户的 Webhook 事件。
若不再想收到相关通知，可使用/business/webhook/delete/删除 Webhook 配置。
请求
地址 https://business-api.tiktok.com/open_api/v1.3/business/webhook/update/
方法 POST
Header
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Content-Type {必填}|string|请求信息类型。<br>允许格式：`application/json`。|
参数
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
| app_id {必填} | string | 开发者应用 ID。<br><br>您可以导航至<strong>[应用管理](https://ads.tiktok.com/marketing_api/apps/)</strong> > <strong>App Detail</strong> > <strong>基本信息</strong>，获取<strong>应用 ID</strong>。|
| secret {必填} | string[] | 开发者应用密钥。<br><br>您可以导航至<strong>[应用管理](https://ads.tiktok.com/marketing_api/apps/)</strong> > <strong>App Detail</strong> > <strong>基本信息</strong>，获取<strong>密钥</strong>。|
| event_type {必填} | string | 想要订阅的 Webhook 事件类型。<br><br>枚举值：<ul><li>`VIDEO`： 帖子发布事件，使您能获取通过某些 TikTok API 接口发布的内容的实时发布状态通知。<ul><li>若想了解此类事件类型中事件的结构和有效负载示例，请查看[帖子发布事件](1810515090228226.html)。 </li></ul></li><li>`COMMENT`：评论更新事件，包括 `comment.update` 事件。<ul><li>若想了解此类事件类型中事件的结构和有效负载示例，请查看[评论更新事件](1810515104773122.html)。</li></ul></li></ul> |
| callback_url {必填} | string | 回调 URL。 |
| item_list | string[] | <ul><li>仅当 `event_type` 设置为 `COMMENT` 时生效。</li><li>当 `event_type` 设置为 `DEFAULT` 或 `VIDEO` 时忽略本字段。</li></ul><br>TikTok 帖子 ID 列表，用于获取这些帖子下评论的更新事件通知。 <br><br>最大数量：100。 <br><br>若想获取某个 TikTok 账号下的 TikTok 帖子的 ID 列表，可使用 [/business/video/list/](1762228421622786.html)。<br><br><ul><li>若请求中 `event_type` 设置为 `COMMENT` 且指定了 `item_list`：<ul><li>开发者应用（`app_id`）从未配置过 `item_list` 时，您将仅接收到请求中通过 `item_list` 指定的帖子的 `comment.update` 事件通知。</li><li>开发者应用（`app_id`）已配置过 `item_list` 时，您接收到之前已配置过的帖子以及请求中通过 `item_list` 指定的帖子的 `comment.update` 事件通知。</li></ul></li><li>若请求中 `event_type` 设置为 `COMMENT` 且未指定 `item_list`：<ul><li>开发者应用（`app_id`）从未配置过 `item_list` 时，您将接收到所有授权过该开发者应用（`app_id`）的 TikTok 账号下所有帖子的 `comment.update` 事件通知。</li><li> 开发者应用（`app_id`）已配置过 `item_list` 时，您接收到之前已配置过的帖子的 `comment.update` 事件通知。若想了解之前已配置过的具体帖子信息，请查看返回中的 `item_list` 字段值。</li></ul></li></ul>|
示例
订阅帖子发布事件
(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/business/webhook/update/' \
--header 'Content-Type: application/json' \
--data '{
"app_id": "{{app_id}}",
"secret": "{{secret}}",
"event_type": "VIDEO",
"callback_url": "{{callback_url}}"
}'
(/code)
订阅所有帖子的评论更新事件
(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/business/webhook/update/' \
--header 'Content-Type: application/json' \
--data '{
"app_id": "{{app_id}}",
"secret": "{{secret}}",
"event_type": "COMMENT",
"callback_url": "{{callback_url}}"
}'
(/code)
订阅指定帖子的评论更新事件
(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/business/webhook/update/' \
--header 'Content-Type: application/json' \
--data '{
"app_id": "{{app_id}}",
"secret": "{{secret}}",
"event_type": "COMMENT",
"callback_url": "{{callback_url}}"
"item_list": ["{{item_id}}", "{{item_id}}"]
}'
(/code)
更新帖子发布事件的回调 URL
(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/business/webhook/update/' \
--header 'Content-Type: application/json' \
--data '{
"app_id": "{{app_id}}",
"secret": "{{secret}}",
"event_type": "VIDEO",
"callback_url": "{{callback_url}}"
}'
(/code)
返回
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|code |number| 返回码。完整返回码列表及描述，参见 [附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string| 返回信息。更多信息参见 [附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。 |
|request_id |string| 请求的日志ID，唯一标识一个请求。 |
|data |object| 返回数据。 |
#| app_id | string | 开发者应用 ID。 |
#| event_type | string | 订阅的 Webhook 事件类型。<br><br>枚举值：<ul><li>`VIDEO`： 帖子发布事件，使您能获取通过某些 TikTok API 接口发布的内容的实时发布状态通知。<ul><li>若想了解此类事件类型中事件的结构和有效负载示例，请查看[帖子发布事件](1810515090228226.html)。 </li></ul></li><li>`COMMENT`：评论更新事件，包括 `comment.update` 事件。<ul><li>若想了解此类事件类型中事件的结构和有效负载示例，请查看[评论更新事件](1810515104773122.html)。</li></ul></li></ul> |
#| callback_url | string | 回调 URL。 |
#| item_list | string[] | 仅当 `event_type` 为 `COMMENT` 且开发者应用（`app_id`）配置了 `item_list` 时返回本字段。 <br><br>TikTok 帖子 ID 列表，用于获取这些帖子下评论的更新事件通知。|
示例
订阅帖子发布事件
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"app_id": "{{app_id}}",
"callback_url": "{{callback_url}}",
"event_type": "VIDEO"
}
}
(/code)
订阅所有帖子的评论更新事件
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"app_id": "{{app_id}}",
"callback_url": "{{callback_url}}",
"event_type": "COMMENT"
}
}
(/code)
订阅指定帖子的评论更新事件
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"app_id": "{{app_id}}",
"callback_url": "{{callback_url}}",
"event_type": "COMMENT",
"item_list": [
"{{item_id}}",
"{{item_id}}"
]
}
}
(/code)
更新帖子发布事件的回调 URL
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"app_id": "{{app_id}}",
"callback_url": "{{callback_url}}",
"event_type": "VIDEO"
}
}
(/code)