Webhooks

Instead of polling, configure a webhook endpoint once and TrueFan will POST to it whenever a request you submitted finishes — one delivery per request, regardless of how many rows it contained.

1. Create an endpoint

curl -X POST "https://dev-backend-ai.truefans.in/api/external/v1/webhooks/" \
  -H "Authorization: Bearer $TRUEFAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://myapp.example.com/webhooks/truefan"}'

Response

{
  "webhook": {
    "endpoint_id": "9d2f1e0a-...",
    "target_url": "https://myapp.example.com/webhooks/truefan",
    "is_active": true,
    "created": "2026-08-21T10:00:00Z"
  },
  "secret": "b1946ac92492d2347c6235b4d2611184..."
}

secret is returned exactly once, in the create response — the same reveal-once posture as the API key itself. Store it now; you’ll need it to verify incoming deliveries.

2. Verify incoming requests

Every delivery is signed with HMAC-SHA256 over the raw request body, using the endpoint’s secret:

import hashlib
import hmac

def verify_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    # signature_header looks like "sha256=<hex digest>"
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

const crypto = require("crypto");

function verifySignature(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

Compute the HMAC over the raw, unparsed request body — not a re-serialized version of the parsed JSON, which can differ in key order or whitespace and produce a mismatched signature.

Request format

header

sha256=<hex-encoded HMAC-SHA256 digest> of the raw body, using your endpoint’s secret.

header

The event type — same value as the event field in the body.

`bulk_job.completed`

Fired once every row in a request has reached a terminal state — whether you sent one row or a thousand, this fires exactly once per request, never once per row.

{
  "event": "bulk_job.completed",
  "bulk_job_id": "8c1f2e3a-...",
  "total": 50,
  "success": 48,
  "failed": 2,
  "csv_export_path": "/api/external/v1/bulk-jobs/8c1f2e3a-.../export.csv"
}

This payload is intentionally just the summary counts, not the full result list. Download the complete batch — every row’s result_video_url, external_id, and generation_id — from Download CSV export; csv_export_path above is that exact path, relative to your API host, ready to fetch as soon as this webhook arrives.

Delivery & retries

Your endpoint should return a 2xx status within 10 seconds. Anything else is treated as a failure:

Retried with exponential backoff — 30s, 60s, 120s, … up to a 1-hour cap — for up to 6 attempts.
After the final attempt fails, the delivery is marked dead and not retried again.

Check delivery history — including response codes and final status — via List webhook deliveries:

curl "https://dev-backend-ai.truefans.in/api/external/v1/webhooks/{endpoint_id}/deliveries/" \
  -H "Authorization: Bearer $TRUEFAN_API_KEY"

If a delivery shows as dead, your endpoint was unreachable or erroring for the entire retry window — check your own logs for that time range, then fall back to polling for that specific job to recover the result.

Removing an endpoint

curl -X DELETE "https://dev-backend-ai.truefans.in/api/external/v1/webhooks/{endpoint_id}/" \
  -H "Authorization: Bearer $TRUEFAN_API_KEY"

Get Started

Core Concepts

Guides

1. Create an endpoint

2. Verify incoming requests

Request format

`bulk_job.completed`

Delivery & retries

Removing an endpoint

​1. Create an endpoint

​2. Verify incoming requests

​Request format

​bulk_job.completed

​Delivery & retries

​Removing an endpoint

1. Create an endpoint

2. Verify incoming requests

Request format

`bulk_job.completed`

Delivery & retries

Removing an endpoint