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:https://<your domain><webhook api>
<your domain> with your domain name and <webhook api> with the Webhook API path you have configured.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.
Modified at 2025-01-22 05:48:43
