Webhooks

A webhook is an HTTP endpoint of yours that Mynth POSTs to when a task completes or fails. Use one when the code that creates the task cannot wait for it: serverless handlers, request/response paths where a user is waiting, and long video renders. If your code can hold a connection, await the SDK call or poll instead.

How delivery works

task settles
  │
  ▼
POST https://your-app.com/api/mynth-webhook
  headers: webhook-id, webhook-timestamp, webhook-signature
  body:    { id, type, timestamp, data: <the task> }
  │
  ├─ 2xx within 30 s ──▶ done
  └─ anything else ────▶ retried: 5 s, 10 s, 20 s … up to 1 h apart, for about 72 h
                          same webhook-id on every attempt

Deliveries follow Standard Webhooks, and data is the task exactly as GET /tasks/{id} returns it. The headers and body are on webhook payloads.

A task reaches two kinds of endpoint:

Creating the task needs nothing extra: every registered endpoint that subscribed to the event receives it. Each endpoint gets its own delivery, so one failing endpoint never holds back another.

Register an endpoint

npx @mynthio/cli webhook create \
  --url https://your-app.com/api/mynth-webhook \
  -e task.image.generate.completed \
  -e task.image.generate.failed

The URL must be https on a public host. The response carries a whsec_... signing secret. Store it where your app reads environment variables:

MYNTH_WEBHOOK_SECRET=whsec_...

The API and the CLI return the secret only on create. The endpoint's page in the dashboard keeps showing it. Webhook endpoints need a key with the manage scope. The key from npx @mynthio/cli auth login has it.

PUT /webhooks/{id} replaces the whole configuration, so send url, events, and enabled every time. An omitted include_session_tasks becomes false, and an omitted api_key_ids becomes every key. npx @mynthio/cli webhook update behaves the same way. DELETE /webhooks/{id} removes the endpoint and its secret.

Receive events

The SDK helpers verify the signature and call the handler for the event. They answer 200 for an event with no handler, including event types newer than the SDK, so subscribe only to what you handle. Every helper takes the handlers below, image and video alike, plus onEvent, which receives every event before its handler runs.

Next.js

// app/api/mynth-webhook/route.ts
import { mynthWebhookHandler } from "@mynthio/sdk/next";

export const POST = mynthWebhookHandler({
  imageTaskCompleted: async (result) => {
    for (const image of result.images) {
      console.log(result.taskId, image.url ?? image.mynthUrl);
    }
  },
  imageTaskFailed: async (failure) => {
    console.error(failure.taskId, failure.errors);
  },
});

The handler reads the secret from MYNTH_WEBHOOK_SECRET on each request, or from { webhookSecret } as the second argument. It answers 400 for a missing or wrong signature, a webhook-timestamp more than five minutes off, a missing webhook-id, and a body whose id is not the webhook-id.

Completed callbacks receive the same plain result objects as polling, including taskId, cost, and successful media. Failed callbacks receive taskId, errors, and raw, plus metadata when the request supports it. The callback objects can be passed directly to server functions and Convex mutations. The second argument carries the verified event; deduplicate on event.id. See generating media.

TanStack Start

// src/routes/api/mynth-webhook.ts
import { createFileRoute } from "@tanstack/react-router";
import { mynthWebhookHandler } from "@mynthio/sdk/tanstack-start";

export const Route = createFileRoute("/api/mynth-webhook")({
  server: {
    handlers: {
      POST: mynthWebhookHandler({
        imageTaskCompleted: async (result) => {
          console.log(result.taskId, result.images);
        },
      }),
    },
  },
});

Same checks as the Next.js helper. TanStack Start covers the callback context.

Convex

// convex/http.ts
import { httpRouter } from "convex/server";
import { mynthWebhookAction } from "@mynthio/sdk/convex";

import { internal } from "./_generated/api";

const http = httpRouter();

export const mynthWebhook = mynthWebhookAction({
  imageTaskCompleted: async (result, { context }) => {
    await context.runMutation(internal.images.save, {
      taskId: result.taskId,
      images: result.images,
    });
  },
});

http.route({ path: "/mynth-webhook", method: "POST", handler: mynthWebhook });

export default http;

Same checks as the Next.js helper. Convex covers the action context.

Any other stack

Use a Standard Webhooks library. There is one for most languages, and each takes the whsec_ secret as it is. Without the SDK, verifyWebhook() does the same in TypeScript:

import http from "node:http";
import { Webhook } from "standardwebhooks";

const SECRET = process.env.MYNTH_WEBHOOK_SECRET;
if (!SECRET) throw new Error("MYNTH_WEBHOOK_SECRET is required");

const webhook = new Webhook(SECRET);

http
  .createServer((req, res) => {
    const chunks = [];
    req.on("data", (chunk) => chunks.push(chunk));
    req.on("end", () => {
      let event;
      try {
        event = webhook.verify(Buffer.concat(chunks).toString("utf8"), req.headers);
      } catch {
        res.writeHead(400).end("Bad signature");
        return;
      }

      res.writeHead(200).end("OK");
      // do the slow work after answering, once per event.id
      console.log(event.id, event.type, event.data.id);
    });
  })
  .listen(3000);

To verify by hand, the signing scheme is on webhook payloads.

Events

Subscribe an endpoint to exact events, to a status across all task types, or to everything:

The event type is always the exact name, such as task.image.alt.completed, never all. An endpoint that matches through several of its subscriptions still gets one delivery. The body and an example for every task type are on webhook payloads.

Sources

An endpoint receives only tasks from the sources it allows:

Tasks from the CLI carry the API key that auth login stored, so they deliver on the default. You can also set sources in the endpoint's Sources section in the dashboard.

Delivery behavior

Deliveries are at least once. Make the handler idempotent: store the webhook-id and skip one you have already handled. The ID is the same on every retry and to every endpoint, and the SDK helpers pass it as event.id. Answer first and do slow work afterwards, because a handler that runs past 30 seconds counts as a failure and is retried.

A URL that resolves to a private, loopback or link-local address is refused when the delivery connects, and is not retried.

Per-request webhooks

POST /image/generate, POST /image/remove-background, POST /image/upscale, and POST /video/generate take a webhook field for one-off URLs that are not registered:

{
  "model": "black-forest-labs/flux.2-pro",
  "prompt": "A lighthouse at dusk, film grain",
  "webhook": {
    "registered": false,
    "custom": [{ "url": "https://your-app.com/hooks/mynth?token=9f2c1e7b4a0d" }]
  }
}

custom takes up to five https URLs on public hosts. Each one receives this task's event, completed or failed, whatever events your registered endpoints subscribe to. registered: false skips your registered endpoints for this task. Rate, alt text, and review requests do not take webhook.

The SDK helpers reject unsigned deliveries unless you pass unsigned, which replaces the signature check with yours:

// app/api/mynth-webhook/one-off/route.ts
import { timingSafeEqual } from "node:crypto";
import { mynthWebhookHandler } from "@mynthio/sdk/next";

const TOKEN = Buffer.from(process.env.MYNTH_CUSTOM_WEBHOOK_TOKEN ?? "");

export const POST = mynthWebhookHandler(
  {
    imageTaskCompleted: async (result) => {
      console.log(result.taskId, result.images);
    },
  },
  {
    unsigned: {
      verify: (request) => {
        const token = Buffer.from(new URL(request.url).searchParams.get("token") ?? "");
        return TOKEN.length > 0 && token.length === TOKEN.length && timingSafeEqual(token, TOKEN);
      },
    },
  },
);

verify returning false answers 401. The event is still checked: its body must be a Mynth event whose id is the webhook-id.

Testing locally

There is no test-event generator. A real task is cheap enough. Expose your local server with a tunnel, register the tunnel URL, and create a task:

ngrok http 3000
npx @mynthio/cli webhook create --url https://your-tunnel.ngrok.app/api/mynth-webhook -e all
npx @mynthio/cli image generate -m black-forest-labs/flux.2-klein-4b -p "A lighthouse at dusk"

Subscribing to all while testing means a refused or failed task still sends you something.

Next steps

• Webhook payloads: headers, signature, and the body for each task type.
• Tasks: what completed and failed mean when the POST arrives.
• Poll for results: the alternative when something can wait.