← 返回目录
📁 Use Cases › Webhook subscription

通过订阅 API 订阅广告账号 Webhook 事件

本文介绍如何通过 Webhook 接收以下信息的通知： - 一个或多个广告账号的 spend、impressions、clicks 或 video_play_actions 报表指标数据发生变更 - 线索 - 广告审核状态 - 广告审美疲劳状态 - TikTok 视频与 TikTok One (TTO) 营销活动建立关联 - 广告账号暂时禁用状态 - 涉及一个或多个 API 产品的任意问题的发生、更新或解决

简介

Webhook 是 TikTok 平台内发生特定事件时触发的自动 HTTP 回调，可将实时通知发送到你指定的回调 URL。有了这一机制，你无需通过持续的 API 轮询来获取异步事件信息。TikTok 会在事件数据可用时，立即主动将其发送到你的系统。这些通知将以 JSON 格式通过 HTTPS POST 发送至你为应用配置的回调 URL 中。你可以使用这些实时信息更新系统或触发特定业务流程，确保应用高效、及时地与 TikTok 事件保持同步。

你可以通过广告账号 Webhook 进行订阅，获取关于报表指标数据变更、线索、广告审核状态、广告审美疲劳状态、TTO 视频关联状态、广告账号暂时禁用状态或 API 服务状态的实时更新。

前提条件

  • 你可以访问 TikTok API for Business。更多信息参见快速入门 - 具体步骤。请注意，你需要获取 Marketing API 访问令牌。

步骤

订阅报表指标数据变更

若想订阅报表指标数据变更，需调用 /subscription/subscribe/ 接口。在 callback_url 字段中输入回调 URL，将 subscribe_entity 字段设置为 REPORT_DATA_CHANGE，传入 advertiser_ids，并可以选择定义 notify_frequency 以自定义通知时间范围。

如果你订阅的任意广告账号的 spend、impressions、clicks 和 video_play_actions 报表指标在最近的通知时间范围内发生了变更，你最多会收到一条 Webhook 通知。例如，如果你将 notify_frequency 设置为 5_MINUTE 并通过 advertiser_ids 传入 10 个广告账号 ID，以此订阅了 10 个广告账号，频次为每 5 分钟通知一次，那么在最近 5 分钟内，如果其中 3 个广告账号的报表指标发生变更，你将收到一条 Webhook 通知，包含这 3 个广告账号及其发生变更的指标信息。

如需查看这些报表指标的详细说明，参见基础报表 > 支持的指标。

注意 - 订阅广告账号报表指标数据变更目前为白名单功能。如需使用此功能，请通过白名单管理页面申请加入白名单。 - 若想订阅广告账号报表指标数据变更，需确保已为开发者应用启用报表 > 合并报表权限。

示例

请求

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/subscription/subscribe/' \
--header 'Content-Type: application/json' \
--data '{
  "app_id": "{{app_id}}",
  "secret": "{{secret}}",
  "subscribe_entity": "REPORT_DATA_CHANGE",
  "callback_url": "{{callback_url}}",
  "subscription_detail": {
    "access_token": "{{access_token}}",
    "advertiser_ids": ["{{advertiser_id}}","{{advertiser_id}}"],
    "notify_frequency": "5_MINUTE"
  }
}'
(/code)

返回

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "subscription_id": "{{subscription_id}}"
    }
}
(/code)

如果你不想再接收通知，可以使用 /subscription/unsubscribe/ 取消订阅。

Webhook 返回结果包含以下字段。

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|request_id|number|Webhook 请求的唯一识别 ID。|
|object|integer|订阅的对象。<br>支持的值：<ul><li>`11` =  一个或多个广告账号的任意 `spend`、`impressions`、`clicks` 和 `video_play_actions` 报表指标数据变更。</li></ul>|
|time|integer|Unix 时间戳，表明事件通知发送的时间（而不是触发通知的变更发生的时间）。|
|entry|object[]|包含描述报表指标数据变更详情的对象的数组。|
#|data_level|string|订阅的数据层级。<br>支持的值：<ul><li> `advertiser_id`：广告主 ID 层级。</li></ul>|
#|message|string|关于此订阅的其他消息。<br>例如，当你对部分已订阅的广告账号的权限被撤销时，你将收到一条消息。<br>默认情况下，不返回 `message`。|
#|changed_metrics_values|Map (object)|显示每个广告账号报表指标数据变更详情的映射。 <br><ul><li> 键（字符串）：订阅的广告账号的 ID (`advertiser_id`)。</li><li> 值（对象）：在最近一次订阅通知时间范围内，发生变更的广告账号指标及指标的值。指标值根据指标变更当天的 UTC+0 时间进行查询。<ul><li>若想获取订阅的通知时间范围，需使用 [/subscription/get/](1739093832125442.html) 并查看返回的 `notify_frequency`。</li></ul></li></ul>|

返回码示例

(code curl http)
{
  "request_id": {{request_id}},
  "object": 11, // For REPORT_DATA_CHANGE, this field will always be 11.
  "entry": [
    {
      "data_level": "advertiser_id",
      "changed_metrics_values": {
        "{{advertiser_id}}": {
          "currency": "USD",
          "impressions": "5906511",
          "spend": "38444.61",
          "video_play_actions": "5790903",
          "adv_timezone": "Etc/GMT+5",
          "clicks": "10783"
        },
        "{{advertiser_id}}": {
          "video_play_actions": "15261037",
          "adv_timezone": "Atlantic/Reykjavik",
          "clicks": "158131",
          "currency": "USD",
          "impressions": "15362608",
          "spend": "39238.96"
        }
      }
    }
  ],
  "time": 1749202502
}
(/code)

订阅线索

你可以通过 Webhook 将线索收集广告与你的 CRM 系统集成，并实时接收即时表单和私信线索更新。如需了解详情，参见线索收集。

若想订阅线索，需调用 /subscription/subscribe/ 接口。在 callback_url 字段中输入回调 URL，并将 subscribe_entity 字段设置为 LEAD。

  • 对于即时表单线索，将 lead_source 设置为 INSTANT_FORM 或不传入。你可以灵活选择 advertiser_id 或 library_id，其中 page_id 为选填字段。
    • 如果使用 advertiser_id，你将订阅以下所有即时表单线索：通过线索收集广告收集，并且该广告使用与广告账号关联的即时表单。如果包含 page_id，系统将仅通知该广告账号内特定即时表单带来的线索。
    • 如果使用 library_id，你将订阅以下所有即时表单线索：通过线索收集广告收集，并且该广告使用与商务中心内的表单库关联的即时表单。如果包含 page_id，系统将仅通知该表单库内特定即时表单带来的线索。
  • 对于私信线索，将 lead_source 设置为 DIRECT_MESSAGE。你可以灵活选择 advertiser_id 或 library_id，但不支持 page_id。
    • 如果使用 advertiser_id，你将订阅通过与广告账号关联的私信广告收集的线索。
    • 如果使用 library_id，你将订阅通过与表单库关联的私信广告收集的线索。

订阅后，每当有新线索被提交或收集时，你都会收到 Webhook 通知。

注意
TikTok 保证 Webhook“至少成功发送一次”。因此，Webhook 接口可能会收到重复的事件。为避免潜在问题，你可以设计将事件作幂等处理，防止处理重复事件。

示例

请求

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/subscription/subscribe/' \
--header 'Content-Type: application/json' \
--data '{
  "app_id": "{{app_id}}",
  "secret": "{{secret}}",
  "subscribe_entity": "LEAD",
  "callback_url": "{{callback_url}}",
  "subscription_detail": {
    "access_token": "{{access_token}}",
    "advertiser_id": "{{advertiser_id}}"
  }
}'
(/code)

返回

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "subscription_id": "{{subscription_id}}"
    }
}
(/code)

如果你不想再接收通知，可以使用 /subscription/unsubscribe/ 取消订阅。

Webhook 返回结果包含以下字段：

| 字段{25%} | 类型{15%}| 描述{60%} |
| --- | --- | --- |
| request_id | number | Webhook 请求的唯一识别 ID |
| object | integer | 对象类型。<br><br>支持的值：<ul><li>`1`：线索。 </li></ul>|
| entry | object[] | 包含描述变更的对象的数组。属于同一类型但对象不同的多个变更可能会合并为一批返回。 |
#| id | string | 线索 ID。 |
#| lead_source | string | 线索来源。<br><br>枚举值：<ul><li>`INSTANT_FORM`：通过即时表单收集的线索。</li><li>`DIRECT_MESSAGE`：通过已关联企业号的私信收集的线索。</li></ul> |
#| page_id | number | 即时表单的页面 ID。 |
#| page_name | string | 即时表单的页面名称。 |
#| advertiser_id | number | 广告主 ID。 |
#| advertiser_name | string | 广告主名称。 |
#| library_id | number | 表单库 ID。 |
#| campaign_id | number | 推广系列 ID。 |
#| campaign_name | string | 推广系列名称。 |
#| adgroup_id | number | 广告组 ID。 |
#| adgroup_name | string | 广告组名称。 |
#| ad_id | number | 广告 ID。 |
#| ad_name | string | 广告名称。 |
#| create_time | number | 线索创建时间，格式为 Epoch/Unix 时间戳（单位：秒）。<br><br>示例：1743639757。 |
#| changes | object[] | 一个数组，包含描述即时表单或私信线索中已更改字段的对象。 |
##| field | string | 已更改的字段。 |
##| value | object | 该字段的值。 |
| time | integer | 事件通知发送时间，格式为 Epoch/Unix 时间戳（单位：秒）。<br><br>示例：1743702195。 |

返回码示例

(code JSON JSON)
{
  "object": 1,
  "entry": [
    {
      "id": {{id}},
      "page_id": {{page_id}},
      "page_name": "",
      "campaign_id": {{campaign_id}},
      "campaign_name": "{{campaign_name}}",
      "adgroup_id": {{adgroup_id}},
      "adgroup_name": "{{adgroup_name}}",
      "ad_id": {{ad_id}},
      "ad_name": "{{ad_name}}",
      "create_time": 1614239152,
      "changes": [
        {
          "field": "gender",
          "value": "Female"
        },

        {
          "field": "phone_number",
          "value": "15088888888"
        },
        {
          "field": "email",
          "value": "test_email_address@mail.com"
        },
        {
          "field": "address",
          "value": "123 Castro Ave. Mountain View, CA"
        },
        {
          "field": "name",
          "value": "Jane Doe"
        },
        {
          "field": "scheduled_time",
          "value": "Wednesday / 12:00 - 13:00"
        }
      ],
      "advertiser_id": {{advertiser_id}},
      "advertiser_name": "{{advertiser_name}}",
      "library_id": 0,
      "lead_source": "DIRECT_MESSAGE"
    }
  ],
  "time": 1614334356
}
(/code)

订阅广告审核状态

你可以通过 Webhook 进行订阅，获取广告审核状态的实时更新。

若想订阅广告审核状态，需调用 /subscription/subscribe/ 接口，在 callback_url 字段中输入回调 URL，并在 subscribe_entity 字段中传入 AD/AD_GROUP。

示例

请求

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/subscription/subscribe/' \
--header 'Content-Type: application/json' \
--data '{
  "app_id": "{{app_id}}",
  "secret": "{{secret}}",
  "subscribe_entity": "AD_GROUP",
  "callback_url": "{{callback_url}}",
  "subscription_detail": {
    "access_token": "{{access_token}}",
    "advertiser_id": "{{advertiser_id}}",
    "adgroup_id": "{{adgroup_id}}"
  }
}'
(/code)

返回

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "subscription_id": "{{subscription_id}}"
    }
}
(/code)

如果你不想再接收通知，可以使用 /subscription/unsubscribe/ 取消订阅。

注意
只有当你的广告被拒时，你才会收到通知。

Webhook 返回结果包含以下字段。 

| 字段{25%} | 类型{15%} | 描述{60%} |
| --- | ---| ---|
| request_id | number | Webhook 请求的唯一识别 ID |
| object | integer | 对象类型。<br>合法值：<ul><li>`2` = 广告组审核状态。</li><li>`3` = 广告审核状态。 </li></ul> |
| entry | object[] | 包含描述被拒原因的对象的数组。属于同一类型但对象不同的多个变更可能会合并为一批返回。 |
#| log_id | string | 日志 ID |
#| adv_id | number | 广告主 ID |
#| campaign_id | number | 推广系列 ID |
#| campaign_name | string | 推广系列名称 |
#| adgroup_id | number | 广告组 ID |
#| adgroup_name | string | 广告组名称 |
#| ad_id | number | 广告 ID |
#| ad_name | string | 广告名称 |
#|reject_reason | string[] | 广告审核被拒原因 |
| time | int | Unix 时间戳，表明事件通知发送的时间（而不是触发通知的变更发生的时间）。 |

返回码示例

(code JSON JSON)
{
    "request_id": {{request_id}},
    "object": 2,
    "entry": [
            {
                "log_id": "{{log_id}}",
                "adv_id": {{adv_id}},
                "campaign_id": {{campaign_id}},
                "campaign_name": "{{campaign_name}}",
                "adgroup_id": {{adgroup_id}},
                "adgroup_name": "{{adgroup_name}}",
                "reject_reasons": [
                    "The product/service promoted on the ad/landing page belongs to a prohibited industry of the targeted location(s) in your ad when we take our own business evaluation, user experience and the value of advertisement impact, etc. into consideration.",
                    "The product/service displayed in the ad image/video is not consistent with the product/service on the landing page."
                ]
            }
        ],
    "time": 1652917135
}
(/code)

订阅广告审美疲劳状态

你可以通过 Webhook 进行订阅，获取广告审美疲劳状态的实时更新。

若想订阅审美疲劳状态，需调用 /subscription/subscribe/ 接口。在 callback_url 字段中输入回调 URL，传入 advertiser_id 字段并在 subscribe_entity 字段中传入值 CREATIVE_FATIGUE，传入 ad_id 或 adgroup_id 或两者均不传入，以分别订阅一个广告、广告组内所有广告或广告主账号内所有广告的审美疲劳状态。

示例

请求

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/subscription/subscribe/' \
--header 'Content-Type: application/json' \
--data '{
 "app_id": "{{app_id}}",
  "secret": "{{secret}}",
  "subscribe_entity": "CREATIVE_FATIGUE",
  "callback_url": "{{callback_url}}",
  "subscription_detail": {
    "access_token": "{{access_token}}",
    "advertiser_id": "{{advertiser_id}}"
  }
}'
(/code)

返回

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "subscription_id": "{{subscription_id}}"
    }
}
(/code)

如果你不想再接收通知，可以使用 /subscription/unsubscribe/ 取消订阅。

注意
只有当你的广告开始产生创意审美疲劳时，你才会收到通知。

Webhook 返回结果将包含以下字段。

| 字段 {25%}| 类型{15%} | 描述{60%} |
|---|---|---|
| request_id | number | Webhook 请求的唯一识别 ID。 |
| object | integer | 订阅的对象。<br>合法值： <ul><li>`8` = 广告、广告组内的广告或广告主账号内的广告的审美疲劳状态。 </li></ul>|
| entry | object[] | 一个数组，包含描述创意审美疲劳详情的对象。 |
#| adv_id | number | 广告主 ID。 |
#| adgroup_ids | number[] | 当通过 `advertiser_id` 订阅审美疲劳状态时返回。<br>广告组 ID。 |
#| ad_ids| number[] | 当通过 `advertiser_id` 或 `adgroup_id` 订阅审美疲劳状态时返回。<br>广告 ID。 |
#| adgroup_id | number | 当通过 `ad_id` 或 `adgroup_id` 订阅审美疲劳状态时返回。<br>广告组 ID。 |
#| ad_id | number | 当通过 `ad_id` 订阅审美疲劳状态时返回。<br>广告 ID。 |
#| date | string | 检测到你订阅的实体（广告、广告组或广告账号）产生创意审美疲劳的日期。<br>格式：`YYYY-MM-DD`。 |
| time | integer | Unix 时间戳，表明事件通知发送的时间（而不是触发通知的变更发生的时间）。 |

返回码示例

(code JSON JSON)
// Subscribe by adv_id
{
    "request_id": {{request_id}},
    "object": 8,
    "entry": [
        {
            "adv_id": {{adv_id}},
            "adgroup_ids": [
                {{adgroup_id}}
            ],
            "ad_ids": [
                {{ad_id}}
            ],
            "date": "2023-03-24"
        }
    ],
    "time": 1684455332
}

// Subscribe by adgroup_id
{
    "request_id": {{request_id}},
    "object": 8,
    "entry": [
        {
            "adv_id": {{adv_id}},
            "adgroup_id": {{adgroup_id}},
            "ad_ids": [
                {{ad_id}}
            ],
            "date": "2023-03-24"
        }
    ],
    "time": 1684455273
}

// Subscribe by ad_id
{
    "request_id": {{request_id}},
    "object": 8,
    "entry": [
        {
            "adv_id": {{adv_id}},
            "adgroup_id": {{adgroup_id}},
            "ad_id": {{ad_id}},
            "date": "2023-03-24"
        }
    ],
    "time": 1684455179
}
(/code)

订阅 TikTok 视频与 TTO 营销活动的关联

若想接收 TikTok 视频与 TTO 营销活动之间建立关联的实时更新，需调用 /subscription/subscribe/ 接口并将 subscribe_entity 字段设置为 TCM_VIDEOS。

示例

请求

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/subscription/subscribe/' \
--header 'Content-Type: application/json' \
--data '{
 "app_id": "{{app_id}}",
  "secret": "{{secret}}",
  "subscribe_entity": "TCM_VIDEOS",
  "callback_url": "{{callback_url}}",
  "subscription_detail": {
    "access_token": "{{access_token}}",
    "tto_tcm_account_id": "{{tto_tcm_account_id}}"
  }
}'
(/code)

返回

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "subscription_id": "{{subscription_id}}"
    }
}
(/code)

若想取消订阅并停止接收通知，需使用 /subscription/unsubscribe/ 接口。

注意
你将收到与 TTO 营销活动关联的每个视频的通知。如果有多个视频关联同一个营销活动，将生成多条通知。

Webhook 返回结果包含以下字段。 

| 字段 {25%}| 类型{15%}| 描述{60%}|
|---|---|---|
| request_id | number | Webhook 请求的唯一识别 ID。 |
| object | integer | 对象类型。<br><br>支持的值： <ul><li>`10`：TikTok 视频与 TTO 营销活动建立关联。</li></ul>|
| entry | object[] | 视频关联事件详情。属于同一类型但对象不同的多个变更可能会合并为一批返回。 |
#| event_type | string | Webhook 事件类型。<br><br>支持的值：<ul><li>`tto_campaign_webhook`：TTO 视频关联事件。</li></ul> |
#| video_id | integer | 与 TTO 营销活动关联的 TikTok 视频 ID。 |
#| event_time | string | 事件发生时间，采用 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) 格式。<br><br>示例：`2024-11-18T21:57:00.070272Z`。 |
#| handle_name | string | 达人的用户名。 <br><br><p><span style="color:darkred"><b>注意</b></span>：如果无法匹配达人的用户名，不会返回此字段。 |
#| tto_campaign_event_type | string | 特定类型的 TTO 视频关联事件。<br><br>支持的值：<ul><li> `tto_video_uploaded`：TikTok 视频已上传并关联到 TTO 营销活动，但尚未通过审核。</li><li>`tto_video_published`：TikTok 视频已上传并关联到 TTO 营销活动，且已通过审核。 </li></ul>|
#| campaign_id | integer | TTO 营销活动 ID。 |
#| tto_tcm_account_id | integer | TTO Creator Marketplace 账号的 ID。 |
#| log_id | string | 日志 ID。 |
| time | integer | 事件通知发送时间，而不是触发变更发生的时间，格式为 Epoch/Unix 时间戳（单位：秒）。 |

返回码示例

(code JSON JSON)
{
  "request_id":"{{request_id}}",
  "object":10,
  "entry": [
    {
      "event_type":"tto_campaign_webhook",
      "video_id":{{video_id}},
      "event_time":"{{event_time}}",
      "handle_name":"{{handle_name}}",
      "tto_campaign_event_type": "tto_video_published",
      "campaign_id":{{campaign_id}},
      "tto_tcm_account_id":{{tto_tcm_account_id}},
      "log_id":"{{log_id}}"
    }
  ],
  "time": 1731948913
}
(/code)

订阅广告账号暂时禁用状态

若想订阅广告账号暂时禁用状态，需调用 /subscription/subscribe/ 接口。在 callback_url 字段中输入回调 URL，并将 subscribe_entity 字段设置为 AD_ACCOUNT_SUSPENSION。 - 若想订阅属于某个商务中心的所有广告账号，需同时传入 bc_id。 - 若想订阅可能属于不同商务中心的特定广告账号，需同时传入 advertiser_ids。

当你订阅的任意广告账号被暂时禁用或解除暂时禁用时，你将收到 Webhook 通知。

注意
订阅广告账号暂时禁用状态目前为白名单功能。如需使用此功能，请联系你的 TikTok 销售代表。

示例

订阅某个商务中心内所有广告账号的暂时禁用状态

请求

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/subscription/subscribe/' \
--header 'Content-Type: application/json' \
--data '{
  "app_id": "{{app_id}}",
  "secret": "{{secret}}",
  "subscribe_entity": "AD_ACCOUNT_SUSPENSION",
  "callback_url": "{{callback_url}}",
  "subscription_detail": {
    "access_token": "{{access_token}}",
    "bc_id": "{{bc_id}}"
  }
}'
(/code)

返回

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "subscription_id": "{{subscription_id}}"
    }
}
(/code)

订阅多个商务中心内特定广告账号的暂时禁用状态

请求

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/subscription/subscribe/' \
--header 'Content-Type: application/json' \
--data '{
  "app_id": "{{app_id}}",
  "secret": "{{secret}}",
  "subscribe_entity": "AD_ACCOUNT_SUSPENSION",
  "callback_url": "{{callback_url}}",
  "subscription_detail": {
    "access_token": "{{access_token}}",
    "advertiser_ids": ["{{advertiser_id}}","{{advertiser_id}}"]
  }
}'
(/code)

返回

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "subscription_id": "{{subscription_id}}"
    }
}
(/code)

如果你不想再接收通知，可以使用 /subscription/unsubscribe/ 取消订阅。

Webhook 返回结果包含以下字段。 

| 字段 {25%}| 类型{15%}| 描述{60%}|
|---|---|---|
| advertiser_id | string | 广告主 ID。 |
| advertiser_name | string | 广告主名称。 |
| owner_bc_id | string | 该广告账号所属的商务中心 ID。 |
| status | string | 发送 Webhook 时的广告账号状态。<br><br>枚举值： <ul><li>`STATUS_ENABLE`：已解除暂时禁用。 </li><li>`STATUS_LIMIT`：已暂时禁用。</li></ul><br>当你收到 Webhook 时，广告账号状态可能已经变更。若想获取广告账号的最新状态，需使用 [/advertiser/info/](1739593083610113.html) 接口并查看返回的 `status`。 |
| status_change_time | string | 广告账号被暂时禁用或解除暂时禁用的时间，格式为 `YYY-MM-DD HH:MM:SS`（UTC+0 时间）。<br><br>示例：`2025-01-01 00:00:01`。 |
| suspension_reason | string | 仅当 `status` 为 `STATUS_LIMIT` 时返回。<br><br>账号被暂时禁用的原因。 |
| subscription_id | string | 订阅 ID。 |

返回码示例

(code JSON JSON)
{
        "owner_bc_id": "{{owner_bc_id}}",
        "advertiser_id": "{{advertiser_id}}",
        "advertiser_name": "{{advertiser_name}}",
        "status_change_time": "2025-02-19 08:32:29",
        "suspension_reason": "{{suspension_reason}}",
        "status": "STATUS_LIMIT",
        "subscription_id": "{{subscription_id}}"
}
(/code)

订阅 API 服务状态

若想订阅 API 服务状态，需调用 /subscription/subscribe/ 接口。

在 callback_url 字段中传入回调 URL，将 subscribe_entity 设置为 API_SERVICE_STATUS，还可选择通过 product_filters 字段传入要监测的 API 产品。 - 若想订阅所有 API 产品，不传入 product_filters。 - 若想订阅特定 API 产品，需在 product_filters 中传入要订阅的产品。

当涉及一个或多个 API 产品的问题发生、更新或解决时，你将收到 Webhook 通知。

示例

请求

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/subscription/subscribe/' \
--header 'Content-Type: application/json' \
--data '{
  "app_id": "{{app_id}}",
  "secret": "{{secret}}",
  "subscribe_entity": "API_SERVICE_STATUS",
  "callback_url": "{{callback_url}}",
  "subscription_detail": {
        "access_token": "{{access_token}}"
    }
}'
(/code)

返回

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "subscription_id": "{{subscription_id}}"
    }
}
(/code)

如果你不想再接收通知，可以使用 /subscription/unsubscribe/ 取消订阅。

Webhook 返回结果包含以下字段：

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|request_id|number|Webhook 请求的唯一识别 ID。|
|object|integer|对象类型。<br><br>支持的值：<ul><li>`14`：API 服务状态。</li></ul>|
|time|integer|事件通知发送时间，格式为 Epoch/Unix 时间戳（单位：秒）。<br><br>示例：`1743702195`。|
|entry|object[]|事件详情。属于同一类型但对象不同的多个变更可能会合并为一批返回。|
#|incident_id|string|问题 ID。|
#|incident_title|string|问题标题。|
#|incident_products|string[]|受该问题影响的 API 产品列表。<br><br>枚举值：<ul><li>`BUSINESS_CENTER_API`：商务中心 API。</li><li>`CREATIVES_API`：创意 API。</li><li>`CATALOG_API`：商品库管理工具 API。</li><li>`TIKTOK_STORE_API`：TikTok 店铺 API。</li><li>`CAMPAIGN_API`：推广系列管理 API。</li><li>`REPORTING_API`：报告 API。</li><li>`AUDIENCE_API`：受众 API。</li><li>`STREAMING_API`：流媒体 API。</li><li>`EVENTS_API`：事件 API。</li><li>`ACCOUNTS_API`：账号 API。</li><li>`MENTIONS_API`：提及 API。</li><li>`TIKTOK_ONE_API`：TikTok One API。</li><li>`DISCOVERY_API`：发现 API。</li><li>`SPARK_RECOMMEND_API`：Spark Ads 推荐 API。</li><li>`BUSINESS_MESSAGING_API`：Business Messaging API。</li></ul>|
#|incident_event_type|string|与该问题相关的事件类型。<br><br>枚举值：<ul><li>`CREATE`：问题发生。</li><li>`UPDATE`：问题已更新。</li><li>`RESOLVE`：问题已解决。</li></ul>|
#|incident_level|string|问题造成的干扰程度。<br><br>枚举值：<ul><li>`LOW_DISRUPTION`：轻微干扰。可能会出现延迟增加或超时等小问题，但大多数请求仍会成功。</li><li>`MAJOR_DISRUPTION`：重大干扰。服务受到严重影响，大部分或全部 API 调用失败，或全局延迟超过 SLA 阈值。</li></ul>|
#|incident_start_time|string|问题发生时间，格式为 `YYYY-MM-DD HH:MM:SS`（UTC 时间）。|
#|incident_resolve_time|string|问题解决时间，格式为 `YYYY-MM-DD HH:MM:SS`（UTC 时间）。|
#|incident_detail|string|问题描述。|

返回码示例

(code JSON JSON)
{
 "entry": [
    {
      "incident_detail": "We are actively investigating and will provide updates here as they become available.",
      "incident_event_type": "CREATE",
      "incident_id": "{{incident_id}}",
      "incident_level": "LOW_DISRUPTION",
      "incident_products": [
        "BUSINESS_CENTER_API",
        "CREATIVES_API",
        "CATALOG_API",
        "TIKTOK_STORE_API",
        "CAMPAIGN_API",
        "AUDIENCE_API",
        "REPORTING_API",
        "EVENTS_API",
        "STREAMING_API",
        "ACCOUNTS_API",
        "MENTIONS_API",
        "TIKTOK_ONE_API",
        "DISCOVERY_API",
        "SPARK_RECOMMEND_API",
        "BUSINESS_MESSAGING_API"
      ],
      "incident_start_time": "2025-01-01 23:58:59",
      "incident_title": "{{incident_title}}"
    }
  ],
  "object": 14,
  "request_id": {{request_id}},
  "time": 1758931141
}
(/code)

相关文档

订阅 API

← 通过 Webhook API 订阅 TikTok 账户的 Webhook 事件Subscribe to Business Messaging Webhook events via Webhooks API →

内容来源：TikTok API for Business 官方文档 · 本地归档

在接这个接口时卡住了？
Stuck wiring this API into production? We build ad-delivery tooling on these platforms — campaign automation, reporting pipelines, error-handling and migration between API versions.
联系我们 · Talk to us 每日平台更新简报 →