TOOL API

subscription_subscribe_create

Creates a webhook subscription for reporting metric data changes, ad account suspension status changes, leads, ad group or ad review status, creative fatigue, TCM video linking, or API service status updates. Notifications are sent when the subscribed event occurs, including changes to reporting metrics (`spend`, `impressions`, `clicks`, `video_play_actions`), ad account suspension or unsuspension, new leads, ad rejection during review, creative fatigue, TikTok video linking to a TTO campaign, or API incidents being created, updated, or resolved. For lead generation ads using Instant Forms, subscriptions are based on `subscription_id`, not `page_id`, and a page can belong to multiple subscriptions. `REPORT_DATA_CHANGE` and `AD_ACCOUNT_SUSPENSION` subscriptions are allowlist-only features. If the `access_token` used to configure the webhook is revoked by the developer or advertiser, the subscription stops working; generate a new token and reconfigure the webhook.

ecommerceOAuth1 credits

Call information

Tool slug: tiktok-ads.subscription_subscribe_create
Provider: TikTok for Business
Average response: 0 ms
Calls in 7 days: 0

Input parameters

app_idrequired

ID of your developer application.

callback_urlrequired

Callback URL that receives webhook notifications.

secretrequired

Secret of your developer application.

subscribe_entityrequired

Object to subscribe to. `REPORT_DATA_CHANGE` subscribes to changes in `spend`, `impressions`, `clicks`, and `video_play_actions` for one or more ad accounts and requires `advertiser_ids`; using this value also requires the developer app to have the Reporting > Consolidated Report permission enabled. `AD_ACCOUNT_SUSPENSION` subscribes to ad account suspension status changes. `LEAD` subscribes to leads; webhook delivery is at least once, so duplicate events are possible and handlers should be idempotent. `AD_GROUP` subscribes to ad group review status. `AD` subscribes to ad review status. `TCM_VIDEOS` subscribes to TikTok video linking to a TTO campaign. `CREATIVE_FATIGUE` subscribes to fatigue status for an ad, an ad group's ads, or an advertiser account's ads. `API_SERVICE_STATUS` subscribes to API service status updates.

subscription_detailrequired

Subscription configuration details. Required companion fields depend on `subscribe_entity`: for `REPORT_DATA_CHANGE`, include `advertiser_ids` and optionally `notify_frequency`; for `AD_ACCOUNT_SUSPENSION`, include either `bc_id` or `advertiser_ids`; for `LEAD`, use `advertiser_id` or `library_id` depending on the lead source, with `page_id` allowed only for Instant Form leads; for `AD_GROUP`, include `advertiser_id` and `adgroup_id`; for `AD`, include `advertiser_id` and `ad_id`; for `CREATIVE_FATIGUE`, include `advertiser_id` and optionally `adgroup_id` or `ad_id`; for `TCM_VIDEOS`, include `tto_tcm_account_id`; for `API_SERVICE_STATUS`, optionally include `product_filters`.