Tiktok Ads Webhooks

generated: '2026-08-13'
method: searched
source: https://business-api.tiktok.com/portal/docs?id=1759977800177665
spec_type: none
asyncapi_published: false
asyncapi_note: >-
  TikTok publishes no AsyncAPI document for this event surface. Searched the developer portal doc tree
  (1,178 nodes), the tiktok GitHub organisation, and /asyncapi.yaml + /asyncapi.json on
  business-api.tiktok.com — all missed. What follows is the webhook catalog as TikTok documents it in
  prose; nothing here is fabricated and no AsyncAPI was authored on TikTok's behalf.
transport: https-post-json
docs:
  overview: https://business-api.tiktok.com/portal/docs?id=1759977800177665
  event_types: https://business-api.tiktok.com/portal/docs?id=1759978319341570
  verification: https://business-api.tiktok.com/portal/docs?id=1759978341579777
  subscription_use_cases: https://business-api.tiktok.com/portal/docs?id=1810521709205505
subscription:
  mechanism: API
  callback_registration_endpoint: /business/webhook/update/
  callback_docs: https://business-api.tiktok.com/portal/docs?id=1810521279479810
  requirements:
    - The callback URL must be HTTPS.
    - It must return HTTP 200 immediately to acknowledge receipt.
delivery:
  guarantee: at-least-once
  duplicates: expected — TikTok states endpoints may receive the same event more than once
  consumer_requirement: event processing must be made idempotent by the consumer
  retry_policy: exponential backoff for up to 72 hours, then the notification is discarded
  failure_signal: any response other than HTTP 200
message:
  schema_version_header: webhook-schema-version
  current_schema_version: '1.0'
  headers:
    - name: tiktok-signature
      purpose: authenticity — verify the event came from TikTok
      docs: https://business-api.tiktok.com/portal/docs?id=1759978341579777
    - name: webhook-schema-version
      purpose: body schema version
    - name: x-tt-logid
      purpose: unique request identifier for troubleshooting
  body_fields:
    client_key: application ID provisioned for your app on the developer portal
    event: event type name, e.g. post.publish.complete
    create_time: UTC epoch seconds when the event occurred
    user_openid: app-specific unique ID of the TikTok account
    content: serialized JSON string; the only field whose shape varies by event
  shape_note: >-
    The per-event payload is a SERIALIZED JSON STRING inside `content`, not a nested object. Consumers must
    parse twice. This is also why no schema can be inferred per event without the individual event docs.
event_families:
  - family: post publishing
    docs: https://business-api.tiktok.com/portal/docs?id=1759978319341570
    description: >-
      Lifecycle of video and photo posts published to a TikTok account through the publishing endpoints.
    example_event: post.publish.complete
  - family: comment updates
    docs: https://business-api.tiktok.com/portal/docs?id=1759978319341570
    description: New comments and changes to existing comments on posts on your TikTok account.
  - family: mentions
    docs: https://business-api.tiktok.com/portal/docs?id=1825113658431489
  - family: business messaging
    docs: https://business-api.tiktok.com/portal/docs?id=1832190670631937
  - family: ad account events
    docs: https://business-api.tiktok.com/portal/docs?id=1810521739537409
    subscription_api: Subscription API
  - family: API service status
    event: API_SERVICE_STATUS
    docs: https://business-api.tiktok.com/portal/docs?id=1810521739537409
    description: >-
      Real-time incident notifications for TikTok API for Business services, filterable by API product.
      The same signal is available as RSS at
      https://business-api.tiktok.com/marketing_api/api/status_page/incident/rss/
streaming:
  present: true
  note: >-
    TikTok also documents a "Streaming API" in the rate-limit table (10,000 QPS at Basic level), which is a
    distinct high-volume ingest surface from webhooks. No specification or endpoint reference for it was
    found in the public doc tree.
event_ingest_apis:
  note: >-
    Distinct from webhooks (TikTok -> you), TikTok operates a large inbound event surface (you -> TikTok)
    for conversion measurement: Events API 2.0 for Web / App / Offline / CRM (/event/track/), the legacy
    Events API 1.0 (/pixel/track/, /app/track/, /offline/track/) and their batch forms. These are ordinary
    REST endpoints, not an event stream, and are rate-limited at 1,000 QPS at every level.
  docs: https://business-api.tiktok.com/portal/docs?id=1771100779668482