Webhooks and callbacks

Some asynchronous tasks send a callback to your service at callback_url when they finish. Webhooks are useful for long-running video, digital human and music generation tasks.

Request method

MoonNexAI sends a POST request to the supplied callback_url.

For Video task (includes seedance-2.0-sz, seedance-2.0-sz-fast, seedance-2.0-sz-mini and seedance-2.5-sz), callbacks use the same field structure as the official task API. task status changes may be received multiple times callback, with a common order queued -> running -> succeeded or queued -> running -> failed. id of callback is the MoonNexAI Public task ID; please use status and error judges the results of task, not just on the existence of URLs.

{
  "id": "task_01HX...",
  "object": "task",
  "status": "succeeded",
  "model": "seedance-2.0-kz-fast",
  "created_at": 1710000000,
  "content": {
    "video_url": "https://example.com/result.mp4"
  },
  "error": null
}

Failed task contains standard error object:

{
  "id": "task_01HX...",
  "object": "task",
  "status": "failed",
  "error": {
    "message": "Task failed.",
    "type": "task_error",
    "code": "task_failed"
  }
}

Receiving callbacks

• Your webhook endpoint should return 2xx within 10 seconds.
• Callbacks may be delivered more than once. Make the receiver idempotent using task_id.
• If a callback is missing, query the task API to recover its status.
• callback must be a publicly accessible HTTPS URL.
• Callback payloads use the MoonNexAI fields documented here.
• Final success callback may return a temporary signed media URL; it should be downloaded or re-stored during its validity and the complete URL (including query parameters) should be maintained.
• If the final callback has no URL, query the task API or use the video content endpoint as a fallback.
• Receiving a callback does not mean the task succeeded. Handle error first for failed, cancelled or expired tasks.

Security recommendations

• Sets a random path or service authentication for callback addresses.
• Verify whether task_id is a current user or current business order.
• Do not place API Key, user token or order sensitive information in callback URL query.
• The callback log only records the necessary field to avoid the preservation of the complete user media assets or the generation of the result.