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
| Event | Sent when |
|---|---|
generation.completed | A job finished. data is the job, with its output_url and what it cost. |
generation.failed | A job failed. data is the job, with a public error (type, code, message). |
generation.cancelled | A job was cancelled before it finished. |
credits.low_balance | An API balance fell below your alert threshold (sent once per crossing). data: wallet, balance_usd, threshold_usd, organization_id. |
test.ping | Sent 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"]
}'
| Field | Description |
|---|---|
url | Required. A public https URL. |
events | Required. Event names from the table above. |
secret | Optional. Your own signing secret; one is generated if you leave it out. |
max_retries | Optional. Delivery attempts before giving up (default 3). |
The response includes the subscription's signing secret. It is shown only once.
| Method | Path | Description |
|---|---|---|
GET | /notifications/webhooks/subscriptions | List 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}/test | Send a signed test.ping to the URL now |
GET | /notifications/webhooks/subscriptions/{id}/deliveries | Delivery 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:
| Header | Value |
|---|---|
X-FunAI-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256> (see below) |
X-FunAI-Event | The event type, e.g. generation.completed |
X-FunAI-Webhook-Id | ID of this delivery |
X-FunAI-Idempotency-Key | Stable 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
- Read
tandv1fromX-FunAI-Signature. - 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. - Compare with
v1in constant time. - Reject the request if
tis 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
2xxstatus 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-Keyto drop duplicates, and checkdata.statusrather than relying on order. - Redirects are not followed, and URLs must be public
httpsaddresses.