Skip to main content

Webhooks

Webhooks tell your server when a job finishes, so you don't have to poll. FunAI sends an HTTPS POST with a JSON body to a URL you choose.

There are two ways to get them:

  • Per request: add "callback_url": "https://…" to an async job request (/generation/v1/generate…, /v1/videos, /v1/images/generations). Only that job's events go there.
  • Subscription: register a URL once for all your jobs.

Event types​

EventSent when
generation.completedA job finished. data is the job, with its output_url and what it cost.
generation.failedA job failed. data is the job, with a public error (type, code, message).
generation.cancelledA job was cancelled before it finished.
credits.low_balanceAn API balance fell below your alert threshold (sent once per crossing). data: wallet, balance_usd, threshold_usd, organization_id.
test.pingSent when you press "Send test event" or call the test endpoint. Safe to ignore.

Subscribing​

Endpoint: POST /notifications/webhooks/subscriptions

curl https://api.funai.art/notifications/webhooks/subscriptions \
-H "Authorization: Bearer $FUNAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/funai/webhook",
"events": ["generation.completed", "generation.failed"]
}'
FieldDescription
urlRequired. A public https URL.
eventsRequired. Event names from the table above.
secretOptional. Your own signing secret; one is generated if you leave it out.
max_retriesOptional. Delivery attempts before giving up (default 3).

The response includes the subscription's signing secret. It is shown only once.

MethodPathDescription
GET/notifications/webhooks/subscriptionsList your subscriptions
GET/notifications/webhooks/subscriptions/{id}One subscription and its delivery counts
PUT/notifications/webhooks/subscriptions/{id}Change url, events or status (active, paused)
DELETE/notifications/webhooks/subscriptions/{id}Delete a subscription
POST/notifications/webhooks/subscriptions/{id}/testSend a signed test.ping to the URL now
GET/notifications/webhooks/subscriptions/{id}/deliveriesDelivery history, with response codes and errors

Per-request callback_url deliveries are signed with your account signing secret: GET /notifications/webhooks/signing-secret shows it and POST /notifications/webhooks/signing-secret/rotate replaces it.

What we send​

Body:

{
"id": "evt_5f0c7a523a8e4a7e9d510f2a6b9b1c11",
"type": "generation.completed",
"created": 1794507120,
"data": {
"job_id": "8d1f…",
"status": "COMPLETED",
"output_url": "https://…",
"credits_charged": 75,
"usd_equivalent": 0.0075
}
}

data is the job object; failed jobs carry a public error with type, code and message (see Errors).

Headers:

HeaderValue
X-FunAI-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256> (see below)
X-FunAI-EventThe event type, e.g. generation.completed
X-FunAI-Webhook-IdID of this delivery
X-FunAI-Idempotency-KeyStable per event, e.g. <job_id>-<status>. Use it to drop duplicates.

For a transition period we also send the older X-Webhook-Signature: sha256=<hex> (an HMAC of the raw body alone), X-Webhook-Id and X-Webhook-Event. New integrations should verify X-FunAI-Signature.

Verifying the signature​

  1. Read t and v1 from X-FunAI-Signature.
  2. Compute HMAC-SHA256 with your secret over the string "<t>.<raw body>", where the raw body is the exact bytes received, before any JSON parsing.
  3. Compare with v1 in constant time.
  4. Reject the request if t is more than 5 minutes from your clock (replay protection).
const crypto = require('crypto');

// rawBody: Buffer of the request body exactly as received
function isValid(rawBody, header, secret, toleranceSec = 300) {
const parts = Object.fromEntries((header || '').split(',').map((p) => p.split('=')));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
const a = Buffer.from(expected, 'utf8');
const b = Buffer.from(parts.v1 || '', 'utf8');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
import hashlib, hmac, time

def is_valid(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in (header or "").split(",") if "=" in p)
try:
t = int(parts["t"])
except (KeyError, ValueError):
return False
if abs(time.time() - t) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))

Delivery and retries​

  • Answer with any 2xx status within 10 seconds. Do slow work after you answer.
  • Other answers, timeouts and connection errors are retried with exponential backoff. Every retry sends the same bytes and the same event id.
  • Events can arrive more than once or out of order. Use X-FunAI-Idempotency-Key to drop duplicates, and check data.status rather than relying on order.
  • Redirects are not followed, and URLs must be public https addresses.