Webhooks - Mynth - Documentation

Delivery model

Mynth supports:

dashboard-managed webhooks
task-level custom webhook endpoints

Dashboard-managed webhooks are signed. Task-level custom endpoints are not signed.

Headers

Signed deliveries include:

Header	Meaning
`X-Mynth-Event`	The event name
`X-Mynth-Signature`	HMAC-SHA256 signature in `t=...,v1=...` format

Events

Payloads sent by the worker are image-task payloads:

task.image.generate.completed
task.image.generate.failed
task.image.rate.completed
task.image.rate.failed
task.image.alt.completed
task.image.alt.failed

Dashboard event subscriptions also support hierarchical matching through:

task.completed
task.failed
all

For example, a task.image.generate.completed delivery can satisfy a webhook subscribed to task.completed.

Signature verification

The signature is calculated from:

{timestamp}.{raw_request_body}

using the webhook secret and HMAC-SHA256. The X-Mynth-Signature header format is:

t={timestamp},v1={signature}

Parse the timestamp and signature from the header, then recompute the HMAC over {timestamp}.{raw_request_body} using your webhook secret. Compare the result to the v1 value. See Use Webhooks for a complete code example.

`task.image.generate.completed` payload

{
  "event": "task.image.generate.completed",
  "task": { "id": "tsk_123" },
  "request": {
    "prompt": "A campaign image for a summer travel brand"
  },
  "result": {
    "model": "google/gemini-3.1-flash-image",
    "images": [
      {
        "status": "success",
        "id": "img_123",
        "url": "https://...",
        "mynth_url": "https://...",
        "size": "1024x1024",
        "cost": "0.01250000"
      }
    ]
  }
}

`task.image.generate.failed` payload

Failed tasks do not include a result object because generation did not produce images. Failure detail is in errors instead.

{
  "event": "task.image.generate.failed",
  "task": { "id": "tsk_123" },
  "request": {
    "prompt": "A campaign image for a summer travel brand"
  },
  "errors": [
    {
      "code": "RESTRICTED_CONTENT",
      "message": "The request was blocked by content moderation."
    }
  ]
}

`task.image.rate.completed` payload

{
  "event": "task.image.rate.completed",
  "task": { "id": "tsk_456" },
  "request": {
    "url": "https://example.com/image.png",
    "mode": "nsfw_sfw"
  },
  "result": {
    "url": "https://example.com/image.png",
    "level": "sfw"
  }
}

`task.image.rate.failed` payload

{
  "event": "task.image.rate.failed",
  "task": { "id": "tsk_456" },
  "request": {
    "url": "https://example.com/image.png",
    "mode": "nsfw_sfw"
  },
  "errors": [
    {
      "code": "FETCH_FAILED",
      "message": "The image could not be fetched."
    }
  ]
}

`task.image.alt.completed` payload

{
  "event": "task.image.alt.completed",
  "task": { "id": "tsk_789" },
  "request": {
    "url": "https://example.com/image.png"
  },
  "result": {
    "url": "https://example.com/image.png",
    "alt": "A ceramic mug on a wooden table beside a window."
  }
}

`task.image.alt.failed` payload

{
  "event": "task.image.alt.failed",
  "task": { "id": "tsk_789" },
  "request": {
    "url": "https://example.com/image.png"
  },
  "errors": [
    {
      "code": "ALT_GENERATION_FAILED",
      "message": "Alt text generation failed."
    }
  ]
}

`errors` on failed deliveries

Every *.failed delivery includes an errors array. The array is always non-empty. Each entry is:

Field	Required	Meaning
`code`	Yes	Stable `SCREAMING_SNAKE_CASE` identifier — safe to branch on
`message`	No	Human-readable detail — informational only; do not parse

This is the same errors array returned by GET /tasks/:id for failed tasks. See Task error codes for the full code list.

​Delivery model

​Headers

​Events

​Signature verification

​task.image.generate.completed payload

​task.image.generate.failed payload

​task.image.rate.completed payload

​task.image.rate.failed payload

​task.image.alt.completed payload

​task.image.alt.failed payload

​errors on failed deliveries