Use Webhooks

Use webhooks when a finished task should trigger backend work — persist results, update records, moderate, or fan out to other systems. Mynth POSTs a JSON payload to your endpoint when a task completes or fails. For live browser progress, use Async and polling or Browser Polling instead. You can combine both: poll for the UI and still receive webhooks for durable server-side handling. Event names, headers, and full payload shapes are listed in the Webhooks reference.

Register a dashboard webhook

Dashboard-managed webhooks are the default production path. They are reusable across tasks and signed with HMAC-SHA256.

Open the webhooks dashboard.
Create a webhook with your HTTPS endpoint and the events you care about.
Save the signing secret when it is shown — you need it to verify deliveries.

Once enabled, matching tasks send webhooks automatically. You do not need a webhook field on each generate request.

const task = await mynth.image.generate({
  prompt: "Packaging concept for a botanical tea brand",
  model: "google/gemini-3.1-flash-image",
});

// Task is accepted; your endpoint receives the result when it finishes
console.log(task.id);

Handle a delivery

Every delivery is an HTTP POST with Content-Type: application/json.

Header	Present on	Meaning
`X-Mynth-Event`	All deliveries	Specific event name (for example `task.image.generate.completed`)
`X-Mynth-Signature`	Dashboard-managed webhooks only	HMAC-SHA256 signature in `t=...,v1=...` format
`Content-Type`	All deliveries	`application/json`

Respond with a 2xx status as soon as you accept the payload. Treat deliveries as at-least-once: make handlers idempotent using task.id.

Completed generate task

{
  "event": "task.image.generate.completed",
  "task": {
    "id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP"
  },
  "request": {
    "prompt": "Packaging concept for a botanical tea brand",
    "model": "google/gemini-3.1-flash-image"
  },
  "result": {
    "model": "google/gemini-3.1-flash-image",
    "images": [
      {
        "status": "success",
        "id": "img_123",
        "url": "https://...",
        "mynth_url": "https://...",
        "size": "1024x1024",
        "cost": "0.01250000"
      }
    ]
  }
}

Failed generate task

Failed tasks include event, task, request, and errors. They do not include result.

{
  "event": "task.image.generate.failed",
  "task": {
    "id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP"
  },
  "request": {
    "prompt": "Packaging concept for a botanical tea brand",
    "model": "google/gemini-3.1-flash-image"
  },
  "errors": [
    {
      "code": "RESTRICTED_CONTENT",
      "message": "The request was blocked by content moderation."
    }
  ]
}

Branch on errors[0].code. Treat client-side failures as terminal; retry only when the code is transient:

const code = payload.errors[0]?.code;

if (code === "RESTRICTED_CONTENT" || code === "INVALID_PROMPT") {
  // Terminal — fix the prompt or content before submitting again
  await markFailed(payload.task.id, code);
} else if (code === "RATE_LIMITED" || code === "TIMEOUT" || code === "PROVIDER_ERROR") {
  // Transient — safe to resubmit the same request
  await enqueueRetry(payload.request);
} else {
  await markFailed(payload.task.id, code ?? "UNKNOWN_ERROR");
}

See Task error codes for the full list. request is the task request as stored by Mynth (including metadata when you set it). See Use Metadata. For rate and alt payloads, see the Webhooks reference.

Verify webhook signatures

Dashboard-managed deliveries include X-Mynth-Signature. Verify it before trusting the body. Header format:

t={timestamp},v1={signature}

Signed message:

{timestamp}.{raw_request_body}

Use HMAC-SHA256 with your webhook secret. Always verify against the raw request body — not a parsed and re-serialized object.

import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhookSignature(signatureHeader: string, rawBody: string, secret: string): boolean {
  const parts = Object.fromEntries(signatureHeader.split(",").map((part) => part.split("=", 2)));
  const timestamp = parts["t"];
  const expected = parts["v1"];
  if (!timestamp || !expected) return false;

  const computed = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  const expectedBuf = Buffer.from(expected, "utf8");
  const computedBuf = Buffer.from(computed, "utf8");
  if (expectedBuf.length !== computedBuf.length) return false;

  return timingSafeEqual(expectedBuf, computedBuf);
}

Get the secret from the webhooks dashboard when you create the webhook. For Convex, use @mynthio/sdk/convex — see Convex integration.

Attach request-level custom webhooks

On image.generate only, you can add up to 5 extra endpoints per task with webhook.custom. These are useful for task-specific or temporary URLs.

const task = await mynth.image.generate({
  prompt: "Packaging concept for a botanical tea brand",
  model: "google/gemini-3.1-flash-image",
  webhook: {
    custom: [{ url: "https://example.com/api/mynth-webhook?token=abc123" }],
  },
});

Custom endpoints are not signed. Put your own verification token in the path or query string (as above), or use another shared secret your backend checks. To skip dashboard-managed webhooks for one task while still sending custom endpoints:

const task = await mynth.image.generate({
  prompt: "Packaging concept for a botanical tea brand",
  model: "google/gemini-3.1-flash-image",
  webhook: {
    dashboard: false,
    custom: [{ url: "https://example.com/api/mynth-webhook?token=abc123" }],
  },
});

Constraint	Limit
Custom endpoints per generate task	1 to 5
Custom endpoint shape	`{ url: string }`
Signature on custom endpoints	None — add your own token or secret check
`webhook` on rate / alt requests	Not supported; use dashboard webhooks

Choose events

Mynth delivers these concrete events:

Event	When it fires
`task.image.generate.completed`	Image generation task succeeded
`task.image.generate.failed`	Image generation task failed
`task.image.rate.completed`	Standalone rating task succeeded
`task.image.rate.failed`	Standalone rating task failed
`task.image.alt.completed`	Alt text task succeeded
`task.image.alt.failed`	Alt text task failed

When you subscribe in the dashboard, you can also use broader filters:

Subscription	Matches
`task.completed`	Any `*.completed` event above
`task.failed`	Any `*.failed` event above
`all`	Every event

The X-Mynth-Event header and payload.event always use the specific event name (for example task.image.generate.completed), even if the webhook was subscribed with task.completed or all. Generation-time content rating (rating on generate) does not emit task.image.rate.*. Rating is attached to the generate result; see Use Content Rating.

Delivery retries

Mynth retries failed deliveries (non-2xx or network errors) with exponential backoff and jitter, up to 12 attempts. For dashboard-managed webhooks, consecutive failures are tracked. After 30 consecutive failed delivery attempts, Mynth disables that webhook. Fix the endpoint, then re-enable it in the dashboard. Custom request-level endpoints are not auto-disabled; retries still apply for that job.

REST example

curl https://api.mynth.io/image/generate \
  -X POST \
  -H "Authorization: Bearer $MYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Packaging concept for a botanical tea brand",
    "model": "google/gemini-3.1-flash-image",
    "webhook": {
      "custom": [
        { "url": "https://example.com/api/mynth-webhook?token=abc123" }
      ]
    }
  }'

If you already have a dashboard webhook subscribed to generate events, omit webhook and rely on that registration.

When to use webhooks vs polling

Approach	Best for
Webhooks	Backend workflows, durable pipelines, cross-system sync
Polling	Browser previews, live progress, short user sessions
Both	UI waits on poll; server persists via webhook

Next steps

Payload reference: Webhooks
Polling and task endpoints: Async and polling
Convex helper: Convex integration
Full Convex walkthrough: Convex full-stack image generation

Getting started

Generation

Control and delivery

Image analysis

Integrations

Register a dashboard webhook

Handle a delivery

Completed generate task

Failed generate task

Verify webhook signatures

Attach request-level custom webhooks

Choose events

Delivery retries

REST example

When to use webhooks vs polling

Next steps

​Register a dashboard webhook

​Handle a delivery

​Completed generate task

​Failed generate task

​Verify webhook signatures

​Attach request-level custom webhooks

​Choose events

​Delivery retries

​REST example

​When to use webhooks vs polling

​Next steps

Register a dashboard webhook

Handle a delivery

Completed generate task

Failed generate task

Verify webhook signatures

Attach request-level custom webhooks

Choose events

Delivery retries

REST example

When to use webhooks vs polling

Next steps