# Webhook

### Webhook Callback Mechanism Documentation  

The Webhook callback mechanism allows you to receive the processing results of asynchronous tasks. By configuring a Webhook URL, you can receive real-time notifications when a task is completed, without needing to poll for the task status.  

## 1. Whitelist Configuration  
To ensure security, we have implemented an IP whitelist mechanism. Please ensure that your server's IP address is added to the whitelist. The currently allowed IP addresses are:  
- `54.212.95.175`  
- `44.236.127.35`  

## 2. Request Information  
- **Request Method**: `POST`  
- **Request URL**:  
  ```
  https://<your domain><webhook api>
  ```  
  Replace `<your domain>` with your domain name and `<webhook api>` with the Webhook API path you have configured.  
- **Request Headers**:  
  ```
  Content-Type: application/json
  ```  

## 3. Request Parameters (Request Body)  
The body of the Webhook request is in JSON format and contains the following fields:  

| **Field Name**   | **Type**   | **Required** | **Description**                                                                 |  
|-------------------|------------|--------------|---------------------------------------------------------------------------------|  
| `taskId`         | `string`   | Yes          | The task ID returned after submitting the task.                                 |  
| `status`         | `integer`  | Yes          | Task status code:                                                               |  
|                   |            |              | - `0`: Task is in progress.                                                    |  
|                   |            |              | - `1`: Task is completed.                                                      |  
|                   |            |              | - `2`: Task has failed.                                                        |  
| `businessId`     | `string`   | No           | The business identifier associated with this task.                              |  
| `type`           | `string`   | Yes          | The type of the task being executed (e.g., `videoEnhancer`, `avatar`, etc.).    |  
| `resultUrl`      | `string`   | No           | The URL of the result file generated after the task is completed.               |  
| `avatarResult`   | `array`    | No           | The result of the generated avatar. See below for field descriptions.           |  

### 3.1 `avatarResult` Field Description  
When the task type (`type`) is `avatar`, the `avatarResult` field will be returned with the following structure:  

| **Field Name**   | **Type**   | **Required** | **Description**                                                                 |  
|-------------------|------------|--------------|---------------------------------------------------------------------------------|  
| `templateId`     | `string`   | Yes          | The ID of the avatar template.                                                 |  
| `images`         | `array`    | No           | An array of avatar images generated using the template. See below for details.  |  

### 3.2 `images` Field Description  
The `images` field in `avatarResult` is an array, with each element containing:  

| **Field Name**   | **Type**   | **Required** | **Description**                                                                 |  
|-------------------|------------|--------------|---------------------------------------------------------------------------------|  
| `id`             | `string`   | Yes          | Image ID.                                                                       |  
| `url`            | `string`   | Yes          | The URL of the avatar image generated using the template.                       |  
| `hasHsfw`        | `boolean`  | Yes          | Indicates whether harmful or sensitive content was detected:                    |  
|                   |            |              | - `false`: No sensitive content.                                               |  
|                   |            |              | - `true`: Sensitive content detected.                                          |  

## 4. Example Webhook Data  
Below is a JSON example for a Webhook request where the task type is `avatar`:  

```json
{
  "taskId": "39371b3800cc4a7e9e24867b0dfdf25b",
  "status": 1,
  "businessId": "75f15294e55540e198bb19cc0a068fd2",
  "type": "avatar",
  "resultUrl": "",
  "avatarResult": [
    {
      "templateId": "d691196a-6daa-4bf9-a011-5422d95ce03f",
      "images": [
        {
          "id": "4a19223cef7b4094a4f66c7de57f7ef4",
          "url": "https://static.fotor.com.cn/aigc/business/75f15294e55540e198bb19cc0a068fd2/avatar/20241126/4a19223cef7b4094a4f66c7de57f7ef4.jpg",
          "hasHsfw": false
        }
      ]
    },
    {
      "templateId": "74d8ef37-4864-480b-927a-dde52e429609",
      "images": [
        {
          "id": "e20cb71b42474fc1a0750cb7627720b5",
          "url": "https://static.fotor.com.cn/aigc/business/75f15294e55540e198bb19cc0a068fd2/avatar/20241126/e20cb71b42474fc1a0750cb7627720b5.jpg",
          "hasHsfw": false
        }
      ]
    },
    {
      "templateId": "7292c5b5-ecb0-4868-b4a4-849c73cc302c",
      "images": [
        {
          "id": "a2773ff7d3534a6ca8735ef7ad4f3f3d",
          "url": "https://static.fotor.com.cn/aigc/business/75f15294e55540e198bb19cc0a068fd2/avatar/20241126/a2773ff7d3534a6ca8735ef7ad4f3f3d.jpg",
          "hasHsfw": false
        }
      ]
    }
  ]
}
```  

## 5. Notes  
- Ensure that your Webhook endpoint can correctly receive and parse the JSON data.  
- We recommend returning an HTTP `200` status code immediately upon receiving a Webhook request to avoid duplicate notifications.  
- If your server cannot access the external network or faces other network restrictions, it may not receive Webhook notifications.