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:

{
  "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.

Webhook Callback Mechanism Documentation#

1. Whitelist Configuration#

2. Request Information#

3. Request Parameters (Request Body)#

3.1 avatarResult Field Description#

3.2 images Field Description#

4. Example Webhook Data#

5. Notes#