Skip to main content

Overview

Rather than polling, an async job can call you back when it reaches a terminal state (completed or failed). Webhooks are available for every async endpoint:
  • POST /transcribe/async
  • POST /extract/video/async
  • POST /tweet/statement/async
  • POST /tiktok/profile
  • POST /tiktok/search

Configure a webhook

There are two ways to set the endpoint, and they combine:

Account default (Studio)

In Studio → API, set a default webhook URL and get your signing secret. Every async job uses it unless the request says otherwise.

Per request (API)

Pass webhook_url in the body of the submit request. It overrides the account default for that job only.
cURL
The URL must be a publicly reachable https URL. Private, loopback and link-local hosts are rejected. The submit response echoes the URL that will be used in data.webhook_url (or null).

The event

When the job finishes, VidNavigator sends a POST with a JSON body to your URL.

Event types

TikTok events are notifications, not payloads. A scrape can hold thousands of videos, so tiktok_profile.* and tiktok_search.* events carry the task stats and point you to check_status_url to read the results (paginated or through download_url).

Headers

Verify the signature

Every delivery is signed with HMAC-SHA256 using your signing secret from Studio → API.
  1. Parse t and v1 from X-VidNavigator-Signature.
  2. Compute HMAC-SHA256(secret, "{t}.{raw_request_body}") as hex. Use the raw body bytes, before any JSON parsing.
  3. Compare with v1 in constant time.
  4. Reject deliveries whose t is more than ~5 minutes old (replay protection).

Delivery and retries

  • Acknowledge with any 2xx, quickly. Do heavy processing asynchronously on your side.
  • Delivery is at-least-once and best effort: up to 5 attempts, backing off over ~13 minutes.
  • Retried: 5xx, 429, timeouts and network errors.
  • Not retried: any other 4xx — it is treated as a permanent rejection.
  • Because the same event can arrive more than once, make your receiver idempotent on X-VidNavigator-Delivery.
  • Treat polling as the source of truth: if a delivery never arrives, the result is still available on check_status_url for 1 hour after the job finishes.

Delivery status on the job

The poll endpoint exposes the delivery state in data.webhook (it is null when no webhook applies). The URL itself is never echoed back, since it frequently embeds a token.

Auto-disable

An account-level default endpoint is switched off automatically when it fails 20 deliveries in a row over more than 72 hours. The owner is notified in Studio.
  • Both conditions must hold: a busy afternoon of failures won’t disable a healthy endpoint, and neither will two failures a week apart.
  • A single successful delivery resets the count.
  • While disabled, jobs still run and results are still available by polling — only the callback stops.
  • Re-enable it in Studio → API once the receiver is fixed.
  • A per-request webhook_url is never auto-disabled, because it is not stored.