REST API

Webhooks

Register an HTTPS endpoint, get a signed event when work settles, and verify it with the standardwebhooks library.

Read as Markdown

Register 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

EndpointScopeLimit per keyWhat it does
GET /webhooksRead120 a minuteLists this workspace's endpoints. Never the secret
POST /webhooksGenerate20 a minuteRegisters one endpoint. Returns the signing secret, once
DELETE /webhooks/{id}Generate20 a minuteRemoves 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
Terminal
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.

Response: 201
{
  "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

FieldTypeNotes
webhook_idstringwh_ prefix
urlstringAs stored, after normalizing
eventsstring[]What this endpoint receives
statusactive | failing | disabledSee endpoint health
consecutive_failuresintegerDeliveries in a row that used every attempt. One success resets it to 0
descriptionstring | null
created_at, updated_atstringISO 8601

Register errors

CauseCodeHTTPRetry
Bad body, unknown key or event name, URL not public https or not resolvable, description too long, or 10 endpoints alreadyinvalid_config400no
Key lacks Generateinsufficient_scope403no
Over 20 changes a minute on this keyrate_limited429yes
Signing is not set up on our sideinternal_error500yes

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
Response: 200
{
  "ok": true,
  "webhook_id": "wh_0193c8f0a1b24e7f9d3c5a6b7e8f00b1",
  "deleted": true
}
  • 200 with a body, never 204. 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:

EventFires whendata
generation.completedA generation completed and its charge was capturedA generation
generation.failedA generation failed and its hold was releasedA generation
batch.settledEvery sibling of a variants submit that fanned out (a video model) has finishedA batch
workflow_run.completedA run ended completed or partialA run
workflow_run.failedA run ended failed or canceledA run
credits.lowAvailable credits fell below the threshold, once per refillCredits
  • webhook.test comes only from Send test in the app, and you can't subscribe to it. Its data is webhook_id plus a message: 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:

Request 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=
HeaderWhat it is
webhook-idThe delivery id (whd_). The same on every retry, and equal to the body's id. Dedupe on it
webhook-timestampUnix seconds of this attempt. A retry hours later carries a fresh one
webhook-signaturev1, then the base64 HMAC SHA-256 of {id}.{timestamp}.{body}, keyed with your signing secret
user-agentRiffAds-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

Body
{
  "id": "whd_0193c8f0a1b24e7f9d3c5a6b7e8f00c1",
  "type": "generation.completed",
  "created_at": "2026-09-17T10:07:39.120Z",
  "data": {}
}
FieldNotes
idSame value as webhook-id
typeThe event name
created_atWhen the event happened, ISO 8601. Not when this attempt was sent
dataOne of the shapes below

Verify every delivery

Check the signature on the raw bytes before you parse or act on anything.

Terminal
npm install standardwebhooks
app/api/riffads/route.ts
import { 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:

  1. Verify on the raw body. verify returns the parsed body and refuses a timestamp more than 5 minutes off, so keep your clock in sync.
  2. Dedupe on webhook-id. A retry, or a copy after a timeout on your side, carries the same id.
  3. Answer any 2XX within 10 seconds. The response body is never read.
  4. 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.

AttemptSent
1Right away
2About 5 minutes after attempt 1
3About 30 minutes after attempt 2
4About 2 hours after attempt 3
5About 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.

statusWhenWhat happens
activeNormalReceives events
failing3 exhausted deliveries in a rowStill receives events
disabled20 exhausted deliveries in a rowReceives nothing
  • One 2XX resets the count to 0 and a failing endpoint to active.
  • Only an owner or admin can enable a disabled endpoint, 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_charged and charge_summary. Never how credits were held.
  • No text result. Read GET /generations/{id} for output_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.

Body: generation.completed
{
  "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.

FieldNotes
statuscompleted or failed. A canceled job reports failed, as on a read
summaryWhat happened, in one or two plain sentences
output_kindimage, 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_chargedWhat it cost. null only while the charge is still being confirmed
batch_group_id, batch_indexSet for a sibling of a variants submit that fanned out
workflow_run_idSet for a workflow step
purposedeliverable, preview, intermediate or null: why the generation exists
errorAn object with code and message on generation.failed, else null
disclosureA 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.

Body: batch.settled (trimmed)
{
  "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": "..."
  }
}
  • status is completed, failed or partial. Never running.
  • Each generations[] entry has the generation event shape, without disclosure.
  • 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.

Body: workflow_run.completed (trimmed)
{
  "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

Body: 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

  1. Register once. POST /webhooks with events: ["generation.completed", "generation.failed"], and store secret.
  2. Submit as usual with POST /generations, and keep the generation_id.
  3. Receive. Verify the delivery, check that webhook-id is new, answer 204, and queue a job.
  4. Use the link. Take outputs[0].url from the body. It never expires, so store it or download it whenever you like. For a text result, read GET /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_url or callback_url. Bodies are strict, so either field is 400 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.

On this page