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

# Webhook

> Callback notifications upon task completion

When a task reaches a terminal state (`SUCCESS` / `FAILURE` / `TIMEOUT` / `CANCELLED`), if a `callBackUrl` was specified at submission time, the system will send a POST request to that URL.

## Callback Format

```
POST <callBackUrl>
Content-Type: application/json
```

The callback `data` field is identical in format to the query endpoint response:

```json SUCCESS theme={null}
{
  "code": 0,
  "msg": "ok",
  "data": {
    "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "SUCCESS",
    "input": {
      "model": "veo3",
      "prompt": "a cat walking in the garden",
      "ratio": "16:9",
      "resolution": "1080p",
      "duration": 10
    },
    "result": {
      "type": "video",
      "urls": ["https://media.example.com/videos/2026/02/26/a1b2c3d4.mp4"]
    },
    "failure_reason": null,
    "created_at": "2026-02-26T07:42:43Z",
    "updated_at": "2026-02-26T10:12:55Z"
  }
}
```

```json FAILURE (content moderation) theme={null}
{
  "code": 0,
  "msg": "ok",
  "data": {
    "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "FAILURE",
    "input": {
      "model": "veo3",
      "prompt": "...",
      "ratio": "16:9",
      "resolution": "1080p",
      "duration": 10
    },
    "result": null,
    "failure_reason": "CONTENT_MODERATION",
    "created_at": "2026-02-26T07:42:43Z",
    "updated_at": "2026-02-26T07:42:55Z"
  }
}
```

## result Field Structure

**On SUCCESS:**

| Field  | Type      | Description                                                                                                    |
| ------ | --------- | -------------------------------------------------------------------------------------------------------------- |
| `type` | string    | Result type: `image` or `video`                                                                                |
| `urls` | string\[] | List of resource URLs. Images may have multiple entries; videos typically have 1. **URLs expire after 7 days** |

**On FAILURE / TIMEOUT / CANCELLED:**

`result` is `null`.

## failure\_reason

Always present in the response. `null` when no specific actionable reason applies.

**Values:**

| Value                 | Meaning                                                                                                     | Recommended Action                                       |
| --------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `CONTENT_MODERATION`  | Prompt or image rejected due to real human faces, copyrighted characters or public figures, or NSFW content | Notify the user; **do not retry**                        |
| `INVALID_PARAMETERS`  | Submitted parameters are invalid                                                                            | Fix request parameters; **do not retry until corrected** |
| `INSUFFICIENT_POINTS` | Account has insufficient credits                                                                            | Prompt user to recharge; **do not retry**                |
| `null`                | No specific actionable reason (transient error, timeout, etc.)                                              | May retry if appropriate                                 |

## Important Notes

<Warning>
  * Webhook timeout is 5 seconds; it is sent asynchronously and does not block the main workflow
  * Failed deliveries are logged only and **will not be retried**
  * `callBackUrl` does not support localhost / 127.0.0.1 or other internal addresses (SSRF protection)
  * The outer `code` is always `0`; use `data.status` to determine success or failure
</Warning>