Best Practices

Overview

Patterns that keep an integration reliable: how to store keys, handle errors, avoid duplicate videos, receive results and keep an eye on costs.

Authentication and security

Store API keys securely

# .env (add it to .gitignore)
HOOKED_API_KEY=your_api_key_here
HOOKED_WEBHOOK_TOKEN=a_long_random_string

Call the API only from your servers. A key in browser or mobile code can be extracted and used to spend your team’s credits.

Use different keys per environment

# .env.development
HOOKED_API_KEY=key_for_development

# .env.production
HOOKED_API_KEY=key_for_production

Separate keys let you delete one without affecting the other.

Rotate keys

Create the new key in Settings → Developer API, deploy it, confirm traffic works, then delete the old key. Deleted keys answer 401 right away.

Error handling

Branch on status and code

async function hooked(path, { method = "GET", body } = {}) {
  const res = await fetch(`https://api.hooked.so/v1${path}`, {
    method,
    headers: { "x-api-key": process.env.HOOKED_API_KEY, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json().catch(() => ({}));
  if (!res.ok) {
    const error = new Error(json.message ?? `HTTP ${res.status}`);
    error.status = res.status;
    error.code = json.code ?? json.errorCode ?? null; // e.g. missing_credentials, INSUFFICIENT_CREDITS, RATE_LIMITED
    error.retryAfter = res.headers.get("Retry-After"); // set on a 429
    error.body = json;
    throw error;
  }
  return json;
}

400: fix the request; the message names the field.
401: check the key.
402: billing. subscription_required, INSUFFICIENT_CREDITS or missing_credentials (with missingProviders).
403: the team lacks the product, or the request uses another team’s files.
404: not found, or not yours.
429: your team is over its rate limit. Wait Retry-After seconds; nothing ran, so any request can be sent again.
5xx: our side.

The full list is in Error Handling.

Retry GETs, not creates

Reading (GET /v1/project/{id}, lists) is safe to retry with backoff:

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function getWithRetry(path, attempts = 4) {
  for (let i = 1; ; i++) {
    try {
      return await hooked(path);
    } catch (error) {
      const retryable = !error.status || error.status === 429 || error.status >= 500;
      if (!retryable || i === attempts) throw error;
      const retryAfter = Number(error.retryAfter); // the Retry-After header of a 429
      await sleep(retryAfter > 0 ? retryAfter * 1000 : 1000 * 2 ** (i - 1)); // 1s, 2s, 4s
    }
  }
}

A create that timed out or answered 5xx may still have created and charged the project. Only retry a create automatically with an Idempotency-Key header, the same key on every attempt: the retry then returns the first answer instead of creating a second project. Without a key, record the attempt, check whether a project exists, and only then decide to send it again.

Avoiding duplicate videos

Send an Idempotency-Key (your job id works) with every create, and guard them on your side too:

Give each job your own id and save it before calling the API.
Send it in metadata ({ "jobId": "job_123" }), so every webhook tells you which job it belongs to.
Save the returned projectId with the job immediately.
If the call failed without an answer, mark the job “unknown” and check your dashboard or GET /v1/video/list before re-sending.

async function createOnce(job) {
  if (job.projectId) return job.projectId; // already created
  if (job.state === "sending") throw new Error(`Job ${job.id} has an unknown outcome; check before re-sending`);

  await saveJob({ ...job, state: "sending" });
  const { data } = await hooked("/project/create/talking-avatar", {
    method: "POST",
    body: { avatarId: job.avatarId, script: job.script, metadata: { jobId: job.id } },
  });
  await saveJob({ ...job, state: "created", projectId: data.projectId });
  return data.projectId;
}

Performance

Cache resources

Avatars, voices and music change rarely. Cache the lists for a few hours instead of fetching them before every video.

const cache = new Map();

async function cached(path, ttlMs = 6 * 60 * 60 * 1000) {
  const hit = cache.get(path);
  if (hit && hit.expires > Date.now()) return hit.value;
  const value = await getWithRetry(path);
  cache.set(path, { value, expires: Date.now() + ttlMs });
  return value;
}

const avatars = await cached("/avatar/list?type=all&limit=100");

Batch operations

Each create starts real work and may charge credits. Keep a few requests in flight at a time rather than firing a whole list at once, and stop the batch on 401 or 402. See Bulk Generation.

Minimize API calls

Use webhooks so you do not need to poll at all, or poll every 10 to 15 seconds rather than every second.
Poll the project you care about (GET /v1/project/{projectId}), not the whole video list.

Webhook implementation

Webhooks plus a polling fallback

Webhooks are the cheapest way to hear about finished videos, but each one is tried only 3 times in a row and then dropped. Keep a periodic job that polls projects you have not heard about for a while.

Protect your endpoint

Every webhook call is signed. Verify the Hooked-Signature header against your signing secret (Settings → Webhooks) and reject anything that does not match or is older than five minutes. See Verify the signature for Node and Python code. A secret token in the webhook URL (?token=...) still works as an extra check, but it is optional. For sensitive actions, confirm the result with GET /v1/project/{projectId} before acting on it.

Handle duplicates

A late answer from your endpoint leads to a retry with the same payload. Make processing idempotent, keyed on videoId (or projectId when videoId is null):

async function handleWebhook(payload) {
  const key = `${payload.data.videoId ?? payload.data.projectId}:${payload.status}`;
  const isNew = await markProcessed(key); // e.g. INSERT ... ON CONFLICT DO NOTHING
  if (!isNew) return;
  // ...process
}

Return 2xx immediately

You have 10 seconds. Acknowledge first, then download the video or update records in the background:

app.post("/hooks/hooked", express.json(), (req, res) => {
  if (req.query.token !== process.env.HOOKED_WEBHOOK_TOKEN) return res.sendStatus(401);
  res.sendStatus(200);
  queue.add("hooked-webhook", req.body); // your job queue
});

Costs

On a managed team, generation is charged in credits. A 402 INSUFFICIENT_CREDITS tells you creditsNeeded and creditsAvailable. Credits for failed projects are refunded automatically.
GET /v1/project/{projectId} returns usedCredits for each project, so you can track spend per job (it goes back to 0 when a failed project is refunded).
On a byok team, generation is billed by your own providers; set up every key your formats need to avoid 402 missing_credentials.
Re-rendering with POST /v1/render is free.

See Credits and your own keys.

Logging and monitoring

Structured logging

Log the ids you need to trace a video end to end:

function logEvent(event, fields) {
  console.log(JSON.stringify({ ts: new Date().toISOString(), event, ...fields }));
}

logEvent("hooked.create", { jobId: "job_123", projectId, format: "talking-avatar" });
logEvent("hooked.webhook", { projectId, videoId, status: "COMPLETED" });

Never log the API key, and strip the webhook token from logged URLs.

Track key metrics

Projects created, completed and failed per day.
Time from create to COMPLETED.
402 responses (credits or keys running out).
Webhooks that never arrived (caught by the polling fallback).

Data validation

Validate before sending

Catch obvious problems before they cost a request:

function validateTalkingAvatar(input) {
  const errors = [];
  if (!input.avatarId) errors.push("avatarId is required");
  if (!input.script?.trim()) errors.push("script is required");
  if (input.script?.length > 10000) errors.push("script is longer than 10,000 characters");
  if (input.webhook && !input.webhook.startsWith("https://")) errors.push("webhook must be https");
  if (input.metadata && JSON.stringify(input.metadata).length > 5 * 1024) errors.push("metadata is over 5 KB");
  return errors;
}

Use ids from the list endpoints rather than hard-coding them.

Testing

Unit test your client

Mock fetch and check how your code handles each answer:

import { test } from "node:test";
import assert from "node:assert";

test("402 missing_credentials surfaces the providers", async () => {
  globalThis.fetch = async () =>
    new Response(
      JSON.stringify({ code: "missing_credentials", errorCode: "MISSING_CREDENTIALS", missingProviders: ["gemini"], message: "..." }),
      { status: 402 }
    );

  await assert.rejects(
    () => hooked("/project/create/talking-avatar", { method: "POST", body: { avatarId: "1", script: "Hi" } }),
    (error) => error.status === 402 && error.code === "missing_credentials"
  );
});

Integration testing

Run real requests against a development key on a few short scripts. Keep these tests out of every CI run: each one creates a real project.

Code organization

Wrap the API in one small module so the base URL, headers, error handling and retries live in one place:

// hooked-client.js
export function createHookedClient({ apiKey, baseUrl = "https://api.hooked.so/v1" }) {
  async function request(path, { method = "GET", body } = {}) {
    const res = await fetch(`${baseUrl}${path}`, {
      method,
      headers: { "x-api-key": apiKey, "Content-Type": "application/json" },
      body: body ? JSON.stringify(body) : undefined,
    });
    const json = await res.json().catch(() => ({}));
    if (!res.ok) {
      const error = new Error(json.message ?? `HTTP ${res.status}`);
      Object.assign(error, { status: res.status, code: json.code ?? json.errorCode ?? null, body: json });
      throw error;
    }
    return json;
  }

  return {
    listAvatars: (query = "") => request(`/avatar/list${query}`),
    listVoices: (query = "") => request(`/voice/list${query}`),
    getProject: (projectId) => request(`/project/${projectId}`),
    getVideo: (videoId) => request(`/video/${videoId}`),
    create: (format, body) => request(`/project/create/${format}`, { method: "POST", body }),
    render: (projectId, webhook) => request("/render", { method: "POST", body: { projectId, webhook } }),
  };
}

Deployment

Environment configuration

const config = {
  apiKey: process.env.HOOKED_API_KEY,
  webhookUrl: `${process.env.PUBLIC_URL}/hooks/hooked?token=${process.env.HOOKED_WEBHOOK_TOKEN}`,
};

for (const [name, value] of Object.entries(config)) {
  if (!value || value.includes("undefined")) throw new Error(`Missing config: ${name}`);
}

Health checks

GET /v1/health needs no API key and reports whether the API is up:

curl "https://api.hooked.so/v1/health"

It answers 200 with status: ok, or 503 with status: error when the database does not answer, plus a timestamp and the database check (services.database). To check that your key still works, call a cheap authenticated endpoint such as GET /v1/avatar/list?limit=1.

Production checklist

Security

API key in a secret store, server-side only; webhook URL protected by a token.

Reliability

GETs retried with backoff; creates never retried blindly; projectId stored right after each create.

Results

Webhook endpoint answers 2xx within 10 seconds and deduplicates; polling fallback for missing webhooks; videos copied to your own storage.

Billing

Enough credits (managed) or every provider key the formats need (byok); 402 alerts in place.

Monitoring

Logs with projectId / videoId; failure rate and time to completion tracked.

Quick reference

Task	Endpoint
List avatars / voices / music	`GET /v1/avatar/list`, `GET /v1/voice/list`, `GET /v1/music/list`
Create a video	`POST /v1/project/create/{format}`
Follow a project	`GET /v1/project/{projectId}`
Get a video	`GET /v1/video/{videoId}`
List videos	`GET /v1/video/list?status=COMPLETED&limit=20`
Re-render a project (free)	`POST /v1/render`
API status	`GET /v1/health`

Getting Started

Core Concepts

AI Agents

Guides

Examples

Overview

Authentication and security

Store API keys securely

Use different keys per environment

Rotate keys

Error handling

Branch on status and code

Retry GETs, not creates

Avoiding duplicate videos

Performance

Cache resources

Batch operations

Minimize API calls

Webhook implementation

Webhooks plus a polling fallback

Protect your endpoint

Handle duplicates

Return 2xx immediately

Costs

Logging and monitoring

Structured logging

Track key metrics

Data validation

Validate before sending

Testing

Unit test your client

Integration testing

Code organization

Deployment

Environment configuration

Health checks

Production checklist

Quick reference

​Overview

​Authentication and security

​Store API keys securely

​Use different keys per environment

​Rotate keys

​Error handling

​Branch on status and code

​Retry GETs, not creates

​Avoiding duplicate videos

​Performance

​Cache resources

​Batch operations

​Minimize API calls

​Webhook implementation

​Webhooks plus a polling fallback

​Protect your endpoint

​Handle duplicates

​Return 2xx immediately

​Costs

​Logging and monitoring

​Structured logging

​Track key metrics

​Data validation

​Validate before sending

​Testing

​Unit test your client

​Integration testing

​Code organization

​Deployment

​Environment configuration

​Health checks

​Production checklist

​Quick reference

Overview

Authentication and security

Store API keys securely

Use different keys per environment

Rotate keys

Error handling

Branch on status and code

Retry GETs, not creates

Avoiding duplicate videos

Performance

Cache resources

Batch operations

Minimize API calls

Webhook implementation

Webhooks plus a polling fallback

Protect your endpoint

Handle duplicates

Return 2xx immediately

Costs

Logging and monitoring

Structured logging

Track key metrics

Data validation

Validate before sending

Testing

Unit test your client

Integration testing

Code organization

Deployment

Environment configuration

Health checks

Production checklist

Quick reference