Skip to main content
Webhooks let Mynth notify your backend when a task finishes, instead of requiring active polling.

​
Two webhook paths

​
Dashboard-managed webhooks

Create these in the dashboard. Use them when you want:
  • durable account-level delivery
  • signed requests
  • reusable configuration across tasks

​
Request-level custom webhooks

Attach these per task: 
webhook: {
  enabled: true,
  custom: [
    { url: "https://example.com/api/mynth-webhook?token=abc123" }
  ]
}
Use them when you need extra task-specific endpoints.

​
Important security difference

Dashboard-managed webhooks are signed. Request-level custom webhook URLs are not signed, so you should add your own verification token in the path or query string.

​
Events

Mynth emits image-task events:
  • task.image.generate.completed
  • task.image.generate.failed
Dashboard event filters also support broader task-level routing such as task.completed, task.failed, and all.

​
Headers

Signed webhook deliveries include:
  • X-Mynth-Event
  • X-Mynth-Signature
The signature format is: 
t={timestamp},v1={signature}
The payload is signed as: 
{timestamp}.{raw_request_body}
with HMAC-SHA256.

​
Verify webhook signatures

Verify the X-Mynth-Signature header before processing the payload: 
import { createHmac } from "crypto";

function verifyWebhookSignature(signatureHeader: string, rawBody: string, secret: string): boolean {
  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=", 2)));
  const timestamp = parts["t"];
  const expectedSignature = parts["v1"];

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

  return computed === expectedSignature;
}
Always use the raw request body (not a parsed and re-serialized object) for verification. Get your webhook secret from the dashboard.

​
Example payload

{
  "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": "succeeded",
        "id": "img_123",
        "url": "https://...",
        "cost": "0.01250000"
      }
    ],
    "cost": {
      "images": "0.01000000",
      "total": "0.01250000"
    }
  }
}

​
Delivery design guidance

Use webhooks for durable backend workflows. Use polling when the user is waiting on a live result in the browser.
Use webhooks when:
  • the result should trigger backend work
  • users do not need a live progress indicator
  • you want durable event-driven integration
Use polling when the browser needs immediate status updates.