Skip to Content

Webhooks

Get called back when an async job finishes instead of polling.

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 /watch/async
  • POST /extract/video/async
  • POST /tweet/statement/async
  • POST /tiktok/profile
  • POST /tiktok/search
  • POST /tiktok/live/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.

webhook_url in the requestResult
omittedThe account default from Studio is used (if one is configured).
"https://…"This URL is used for this job, instead of the default.
"" (empty string)No webhook for this job, even if a default is configured.
cURL
curl -X POST "https://api.vidnavigator.com/v1/transcribe/async" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.instagram.com/reel/C86ZvEaqRmo/",
    "webhook_url": "https://example.com/hooks/vidnavigator"
  }'

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.

{
  "id": "evt_9f2c1b4e8a7d4c1e9b3a5f6d7c8e9a0b",
  "type": "transcribe.completed",
  "created_at": "2026-09-23T12:03:41Z",
  "api_version": "1.0.0",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "task_status": "completed",
    "job_type": "transcribe",
    "check_status_url": "/v1/transcribe/550e8400-e29b-41d4-a716-446655440000",
    "result": {
      "video_info": { "title": "A long podcast episode", "duration": 3540.0 },
      "transcript": [{ "text": "Welcome to the show.", "start": 0.5, "end": 2.1 }]
    },
    "result_truncated": false,
    "error": null
  }
}
FieldDescription
idUnique event id.
typeEvent type (see below).
created_atWhen the event was created.
api_versionAPI version that produced the event.
data.task_idThe job's task_id.
data.task_statuscompleted or failed.
data.job_typeThe job type.
data.check_status_urlWhere to fetch the full result.
data.resultThe job's result — same shape as the synchronous endpoint's data block. Omitted when result_truncated is true.
data.video_infoextract_video events only: the video's metadata, the same video_info the synchronous POST /extract/video returns beside data. Sent even when result_truncated is true.
data.result_truncatedtrue when the result exceeded 256 KB and was left out. Fetch it from check_status_url.
data.errorOn failure: error, message, http_status — the same codes as the synchronous endpoint.

Event types

TypeSent by
transcribe.completed / transcribe.failedPOST /transcribe/async
watch.completed / watch.failedPOST /watch/async
extract_video.completed / extract_video.failedPOST /extract/video/async
tweet_statement.completed / tweet_statement.failedPOST /tweet/statement/async
tiktok_profile.completed / tiktok_profile.failedPOST /tiktok/profile
tiktok_search.completed / tiktok_search.failedPOST /tiktok/search
tiktok_live_search.completed / tiktok_live_search.failedPOST /tiktok/live/search

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

Headers

HeaderDescription
X-VidNavigator-EventSame as type.
X-VidNavigator-DeliveryDelivery id, stable across retries. Deduplicate on it.
X-VidNavigator-Task-IdThe job's task_id.
X-VidNavigator-Signaturet=<unix_ts>,v1=<hmac_sha256 hex>

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).
import hashlib
import hmac
import time

from flask import Flask, abort, request

app = Flask(__name__)
SIGNING_SECRET = b"YOUR_SIGNING_SECRET"
seen_deliveries = set()  # use a persistent store in production

@app.post("/hooks/vidnavigator")
def vidnavigator_webhook():
    header = request.headers.get("X-VidNavigator-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t"), parts.get("v1")
    if not t or not v1 or abs(time.time() - int(t)) > 300:
        abort(400)

    raw_body = request.get_data()
    expected = hmac.new(SIGNING_SECRET, f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, v1):
        abort(401)

    delivery_id = request.headers["X-VidNavigator-Delivery"]
    if delivery_id in seen_deliveries:
        return "", 200  # already processed
    seen_deliveries.add(delivery_id)

    event = request.get_json()
    if event["data"]["task_status"] == "completed":
        ...  # use event["data"]["result"], or fetch check_status_url if result_truncated
    else:
        ...  # event["data"]["error"]
    return "", 200

Verify with the SDK

The Python and JavaScript SDKs (v2.1.0) do steps 1–4 for you. construct_webhook_event / constructWebhookEvent checks the signature and the 5-minute window, then returns the parsed event. Reattaching to the job with its task_id gives you the full, typed result even when the event's result was truncated:

from flask import Flask, request
from vidnavigator import VidNavigatorClient, WebhookSignatureError, construct_webhook_event

app = Flask(__name__)
client = VidNavigatorClient()
SIGNING_SECRET = "YOUR_SIGNING_SECRET"

@app.post("/hooks/vidnavigator")
def vidnavigator_webhook():
    try:
        event = construct_webhook_event(
            request.get_data(),  # raw body
            request.headers.get("X-VidNavigator-Signature"),
            SIGNING_SECRET,
        )
    except WebhookSignatureError:
        return "invalid signature", 400

    # Deduplicate on request.headers["X-VidNavigator-Delivery"] here

    if event.type == "transcribe.completed":
        resp = client.resume_job("transcribe", event.data.task_id).result()
        print(resp.data.transcript)
    elif event.type.endswith(".failed"):
        print(event.data.task_id, event.data.error.error, event.data.error.message)
    return "", 200

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.

"webhook": {
  "status": "failed",
  "attempts": 5,
  "response_status": 503,
  "last_error": "HTTP 503",
  "delivered_at": null
}
FieldDescription
statuspending, delivered or failed.
attemptsDelivery attempts made (max 5).
response_statusHTTP status your endpoint returned on the last attempt.
last_errorLast delivery error, if any.
delivered_atWhen the delivery succeeded.

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.

On this page