Webhooks
Register an HTTPS endpoint, get a signed event when work settles, and verify it with the standardwebhooks library.
Read as MarkdownRegister one HTTPS endpoint, and RiffAds POSTs a signed event to it when a generation, a batch or a workflow run settles, or when credits run low.
An event reports your own work
A delivery carries ids and facts about work in your workspace. Nothing is ever posted to a social platform: What RiffAds does not do.
Routes
| Endpoint | Scope | Limit per key | What it does |
|---|---|---|---|
GET /webhooks | Read | 120 a minute | Lists this workspace's endpoints. Never the secret |
POST /webhooks | Generate | 20 a minute | Registers one endpoint. Returns the signing secret, once |
DELETE /webhooks/{id} | Generate | 20 a minute | Removes one endpoint and its pending deliveries |
- None of them costs credits. At most 10 endpoints per workspace.
- Register and delete need the Generate scope: Authentication.
- Test, rotate, disable, enable and delivery history are in the app only, for owners and admins:
Register an endpoint
POST/api/v1/webhooksAPI key
curl -s -X POST https://app.riffads.com/api/v1/webhooks \
-H "Authorization: Bearer $RIFFADS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/riffads",
"events": ["generation.completed", "generation.failed"],
"description": "Production render worker"
}'Request body
Strict: an unknown key is 400 invalid_config.
Prop
Type
Response
201, with no Location header.
{
"ok": true,
"webhook": {
"webhook_id": "wh_0193c8f0a1b24e7f9d3c5a6b7e8f00b1",
"url": "https://hooks.example.com/riffads",
"events": ["generation.completed", "generation.failed"],
"status": "active",
"consecutive_failures": 0,
"description": "Production render worker",
"created_at": "2026-09-17T10:00:02.114Z",
"updated_at": "2026-09-17T10:00:02.114Z"
},
"secret": "whsec_3kq0aYkFbJ0xw3Nl9Hk9vS8Q6Hn2bT1mY5cR7dP4eWg="
}The secret is shown once
secret is in this answer and nowhere else, so store it in your secret manager now. Lost it? Delete the endpoint and register a new one, or ask an owner or admin to rotate it in the app.
The endpoint object
| Field | Type | Notes |
|---|---|---|
webhook_id | string | wh_ prefix |
url | string | As stored, after normalizing |
events | string[] | What this endpoint receives |
status | active | failing | disabled | See endpoint health |
consecutive_failures | integer | Deliveries in a row that used every attempt. One success resets it to 0 |
description | string | null | |
created_at, updated_at | string | ISO 8601 |
Register errors
| Cause | Code | HTTP | Retry |
|---|---|---|---|
| Bad body, unknown key or event name, URL not public https or not resolvable, description too long, or 10 endpoints already | invalid_config | 400 | no |
| Key lacks Generate | insufficient_scope | 403 | no |
| Over 20 changes a minute on this key | rate_limited | 429 | yes |
| Signing is not set up on our side | internal_error | 500 | yes |
The message names the problem.
List endpoints
GET/api/v1/webhooksAPI key
Answers ok: true and a webhooks array: every endpoint object, newest first, never the secret. No params, no paging.
Delete an endpoint
DELETE/api/v1/webhooks/{id}API key
{
"ok": true,
"webhook_id": "wh_0193c8f0a1b24e7f9d3c5a6b7e8f00b1",
"deleted": true
}200with a body, never204. Pending deliveries go with it.- Another workspace's id, and one already deleted, both answer
404 not_found.
Events
Subscribe to any of these six:
| Event | Fires when | data |
|---|---|---|
generation.completed | A generation completed and its charge was captured | A generation |
generation.failed | A generation failed and its hold was released | A generation |
batch.settled | Every sibling of a variants submit that fanned out (a video model) has finished | A batch |
workflow_run.completed | A run ended completed or partial | A run |
workflow_run.failed | A run ended failed or canceled | A run |
credits.low | Available credits fell below the threshold, once per refill | Credits |
webhook.testcomes only from Send test in the app, and you can't subscribe to it. Itsdataiswebhook_idplus amessage: answer 2XX and ignore it.- Every generation fires, including batch siblings and workflow steps. For finished work only, act on
data.purpose: "deliverable".
The delivery
Every delivery is one POST with a JSON body and these headers:
POST /riffads HTTP/1.1
content-type: application/json
user-agent: RiffAds-Webhooks/1.0
webhook-id: whd_0193c8f0a1b24e7f9d3c5a6b7e8f00c1
webhook-timestamp: 1789639659
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=| Header | What it is |
|---|---|
webhook-id | The delivery id (whd_). The same on every retry, and equal to the body's id. Dedupe on it |
webhook-timestamp | Unix seconds of this attempt. A retry hours later carries a fresh one |
webhook-signature | v1, then the base64 HMAC SHA-256 of {id}.{timestamp}.{body}, keyed with your signing secret |
user-agent | RiffAds-Webhooks/1.0. Allow it by name if a firewall sits in front |
This is the Standard Webhooks scheme, so the standardwebhooks library checks it as it is.
The envelope
{
"id": "whd_0193c8f0a1b24e7f9d3c5a6b7e8f00c1",
"type": "generation.completed",
"created_at": "2026-09-17T10:07:39.120Z",
"data": {}
}| Field | Notes |
|---|---|
id | Same value as webhook-id |
type | The event name |
created_at | When the event happened, ISO 8601. Not when this attempt was sent |
data | One of the shapes below |
Verify every delivery
Check the signature on the raw bytes before you parse or act on anything.
npm install standardwebhooksimport { Webhook, WebhookVerificationError } from "standardwebhooks";
// The whsec_... string exactly as POST /webhooks returned it.
const verifier = new Webhook(process.env.RIFFADS_SIGNING_SECRET!);
export async function POST(request: Request): Promise<Response> {
// The signature covers the exact bytes sent: never re-serialize first.
const rawBody = await request.text();
const headers = {
"webhook-id": request.headers.get("webhook-id") ?? "",
"webhook-timestamp": request.headers.get("webhook-timestamp") ?? "",
"webhook-signature": request.headers.get("webhook-signature") ?? "",
};
let event: { id: string; type: string; created_at: string; data: any };
try {
// Also refuses a timestamp more than 5 minutes off: a replay.
event = verifier.verify(rawBody, headers) as typeof event;
} catch (error) {
if (error instanceof WebhookVerificationError) {
return new Response("invalid signature", { status: 400 });
}
throw error;
}
// A retry resends the same webhook-id. Handle each id once.
if (!(await markDeliverySeen(headers["webhook-id"]))) {
return new Response(null, { status: 204 });
}
// Answer within 10 seconds. Queue the slow part.
await enqueueJob(event);
return new Response(null, { status: 204 });
}
// Your own storage. Make it atomic, such as an insert on a unique column.
declare function markDeliverySeen(webhookId: string): Promise<boolean>;
declare function enqueueJob(event: unknown): Promise<void>;What the receiver must do:
- Verify on the raw body.
verifyreturns the parsed body and refuses a timestamp more than 5 minutes off, so keep your clock in sync. - Dedupe on
webhook-id. A retry, or a copy after a timeout on your side, carries the same id. - Answer any 2XX within 10 seconds. The response body is never read.
- Keep the secret server side. A rotation in the app takes effect at once, for pending retries too.
Retries
Anything but a 2XX within 10 seconds is a failed attempt: a 4XX or 5XX, a timeout, a dropped connection, or a redirect.
| Attempt | Sent |
|---|---|
| 1 | Right away |
| 2 | About 5 minutes after attempt 1 |
| 3 | About 30 minutes after attempt 2 |
| 4 | About 2 hours after attempt 3 |
| 5 | About 12 hours after attempt 4 (about 14.5 hours after the event) |
- After attempt 5 the delivery is exhausted and never sent again.
- Redirects are not followed. A 301, 302, 307 or 308 counts as a failure. Register the final URL.
- The URL is checked again at every attempt. A hostname that now points at a private address fails.
- Deliveries can arrive out of order. Order by the envelope's
created_at, and read the resource for its current state.
Endpoint health
Counted per exhausted delivery, not per attempt. An hour of downtime costs some retries, not the endpoint.
status | When | What happens |
|---|---|---|
active | Normal | Receives events |
failing | 3 exhausted deliveries in a row | Still receives events |
disabled | 20 exhausted deliveries in a row | Receives nothing |
- One 2XX resets the count to 0 and a
failingendpoint toactive. - Only an owner or admin can enable a
disabledendpoint, in the app. Events from while it was disabled are not replayed. - A failure on our side never counts against your endpoint.
What a payload carries
- A
summary: one or two plain sentences on what happened. - Each file's
url: its permanent link. It never expires, so it still works on the last retry, and anyone with it can open the file: Download links. - The charge:
credits_chargedandcharge_summary. Never how credits were held. - No text result. Read
GET /generations/{id}foroutput_text.
The later event wins
A generation can send generation.failed and later generation.completed, when a render written off is recovered and charged. Before you act on a generation event, read GET /generations/{id}.
Generation events
generation.completed and generation.failed.
{
"id": "whd_0193c8f0a1b24e7f9d3c5a6b7e8f00c1",
"type": "generation.completed",
"created_at": "2026-09-17T10:07:39.120Z",
"data": {
"generation_id": "gen_0193c8f0a1b24e7f9d3c5a6b7e8f0041",
"capability_id": "kling_3_pro",
"status": "completed",
"summary": "Your video is ready. Charged 400 credits.",
"output_kind": "video",
"outputs": [
{
"index": 0,
"asset_id": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0042",
"kind": "video",
"url": "https://app.riffads.com/files/ast_0193c8f0a1b24e7f9d3c5a6b7e8f0042?key=q7Hk2mX9pLr4TzVb8NcW1a"
}
],
"outputs_expected": 1,
"outputs_delivered": 1,
"credits_charged": 400,
"charge_summary": "Charged 400 credits.",
"batch_group_id": null,
"batch_index": null,
"workflow_run_id": null,
"purpose": "deliverable",
"error": null,
"created_at": "2026-09-17T10:04:11.482Z",
"completed_at": "2026-09-17T10:07:39.120Z",
"disclosure": "RiffAds never publishes anything on your behalf. Every file this event refers to is AI generated: disclose that wherever you publish it."
}
}Numbers are examples, not prices.
| Field | Notes |
|---|---|
status | completed or failed. A canceled job reports failed, as on a read |
summary | What happened, in one or two plain sentences |
output_kind | image, video, audio, text or null |
outputs[] | index, asset_id, kind and url, the file's permanent link. url is null for a workflow's working file. Empty on a failure and for a text result |
credits_charged | What it cost. null only while the charge is still being confirmed |
batch_group_id, batch_index | Set for a sibling of a variants submit that fanned out |
workflow_run_id | Set for a workflow step |
purpose | deliverable, preview, intermediate or null: why the generation exists |
error | An object with code and message on generation.failed, else null |
disclosure | A fixed sentence: RiffAds posts nothing, and the file is AI generated |
capability_id, outputs_expected, outputs_delivered and completed_at can be null.
batch.settled
Fires once, when no sibling of a variants submit is still running. Image variants never send it, because one image generation holds every take: Variants.
{
"id": "whd_0193c8f0a1b24e7f9d3c5a6b7e8f00c9",
"type": "batch.settled",
"created_at": "2026-09-17T10:09:02.310Z",
"data": {
"batch_group_id": "bg_0193c8f0a1b24e7f9d3c5a6b7e8f0099",
"status": "partial",
"summary": "3 of 4 versions are ready, and the others did not work. Charged 126 credits for the 3 of 4 outputs delivered.",
"variants": 4,
"variants_finished": 4,
"outputs_delivered": 3,
"credits_charged": 126,
"charge_summary": "Charged 126 credits for the 3 of 4 outputs delivered.",
"generations": [
{
"generation_id": "gen_0193c8f0a1b24e7f9d3c5a6b7e8f00a1",
"batch_index": 0,
"status": "completed"
}
],
"disclosure": "..."
}
}statusiscompleted,failedorpartial. Neverrunning.- Each
generations[]entry has the generation event shape, withoutdisclosure. - Each sibling also sends its own
generation.*event if you subscribe to those.
Workflow run events
workflow_run.completed carries status completed or partial. workflow_run.failed carries failed or canceled.
{
"id": "whd_0193c8f0a1b24e7f9d3c5a6b7e8f00d4",
"type": "workflow_run.completed",
"created_at": "2026-09-17T10:12:02.900Z",
"data": {
"workflow_run_id": "wfr_0193c8f0a1b24e7f9d3c5a6b7e8f0077",
"workflow_id": "wf_0193c8f0a1b24e7f9d3c5a6b7e8f0055",
"status": "completed",
"summary": "Your result is ready. Charged 552 credits.",
"credits_estimated": 990,
"credits_charged": 552,
"nodes": [
{
"node_id": "f_video",
"label": "The talking ad",
"status": "completed",
"generation_ids": [
"gen_0193c8f0a1b24e7f9d3c5a6b7e8f0022",
"gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033"
],
"error": null
}
],
"started_at": "2026-09-17T10:04:11.482Z",
"finished_at": "2026-09-17T10:12:02.900Z",
"disclosure": "..."
}
}credits_charged is the whole run's cost. nodes[].generation_ids lists ids only: each generation sends its own event with its files, or read the run with GET /workflow-runs/{id}: Workflows.
credits.low
{
"id": "whd_0193c8f0a1b24e7f9d3c5a6b7e8f00e2",
"type": "credits.low",
"created_at": "2026-09-18T16:25:00.000Z",
"data": {
"available_credits": 640,
"threshold_credits": 1000
}
}- Fires once per refill. A wallet that stays low fires again only after credits are added and it runs low a second time.
- Checked every few minutes, not at the moment of a spend.
- Top up in the app:
Worked example: know when a video is ready
- Register once.
POST /webhookswithevents: ["generation.completed", "generation.failed"], and storesecret. - Submit as usual with
POST /generations, and keep thegeneration_id. - Receive. Verify the delivery, check that
webhook-idis new, answer204, and queue a job. - Use the link. Take
outputs[0].urlfrom the body. It never expires, so store it or download it whenever you like. For a text result, readGET /generations/{id}.
A webhook is a nudge, not your source of truth. Keep a slow backstop, such as GET /generations?updated_since=... every few minutes: Generations.
Not here
- No per-request
webhook_urlorcallback_url. Bodies are strict, so either field is400 invalid_config. - No rotate, enable, test or delivery history over the API. Those are in the app.
- No replay of an exhausted delivery, or of events missed while an endpoint was disabled.
- No MCP tool. An agent waits for results instead: Wait for the result.