> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goenhance.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Callback (Webhook)

> Receive an HTTP notification on your own server when a task status changes, instead of polling the Get Job Status API.

## Overview

All generate endpoints (Video to Video, Video Effects, Face Swap, Image APIs, etc.) accept an optional `custom_callback_url` field inside `args`. 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-reference/tasks/detail) API.

```json theme={null}
{
  "args": {
    "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](/api-reference/tasks/detail)** (`GET /api/v1/jobs/detail`), so you can reuse the same parsing logic:

```json theme={null}
{
  "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](/api-reference/tasks/detail).

## Best Practices

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