Task Callback (Webhook) - GoEnhanceAI API

Overview

All generate endpoints (Video to Video, Video Effects, Face Swap, Image APIs, etc.) accept an optional top-level custom_callback_url field. When provided, GoEnhance sends a POST request to that URL every time the task status changes, so you don’t need to poll the Get Job Status API.

{
  "prompt": "a cute cat",
  "custom_callback_url": "https://your-server.com/goenhance/callback"
}

Requirements

The URL must be a publicly accessible HTTPS endpoint.
Your server must respond with HTTP 200 within 3 seconds. Do any heavy processing asynchronously after responding.

Callback Payload

The request body is identical to the response of Get Job Status (GET /api/v1/jobs/detail), so you can reuse the same parsing logic:

{
  "code": 0,
  "msg": "Success",
  "data": {
    "img_uuid": "37c82d82-8765-4031-8cb3-722df8a668e6",
    "status": "success",
    "type": "mx-image-face-swap",
    "start_time": "2024-10-11T10:55:32.596Z",
    "end_time": "2024-10-11T10:56:00.338Z",
    "model_id": "-1",
    "json": [
      {
        "type": "image",
        "value": "https://openapi-static.goenhance.ai/user/2024/10/11/9dfdb4b5-7ef7-4fe7-93ff-b9eb76cc431d_0.jpg"
      }
    ],
    "job_type": "mx-image-face-swap"
  }
}

The data.status field is one of:

pending: Job is queued and waiting to be processed
processing: Job is currently being processed
success: Job has finished successfully — results are in data.json
failed: Job has failed with an error

Retry Policy

If your server does not respond with HTTP 200 (including timeouts and connection errors), the notification is retried up to 3 times, with a 3-second timeout per attempt. If all attempts fail, the notification is dropped — you can always fall back to polling Get Job Status.

Best Practices

Respond with 200 immediately after receiving the payload, then process it asynchronously.
Make your handler idempotent — deduplicate by img_uuid + status, as the same notification may be delivered more than once due to retries.
Keep polling as a fallback for critical workflows, in case your endpoint is temporarily unreachable.

​Overview

​Requirements

​Callback Payload

​Retry Policy

​Best Practices

Overview

Requirements

Callback Payload

Retry Policy

Best Practices