Webhook
Upon task completion or failure, we will send an HTTP POST request to your configured Webhook URL.
You can set the webhook_url when creating a task, and we will send a post request to your url.
Tip: Webhooks are convenient, but you can still use other methods to get task generation results. You can also poll the Check Task API to check the task status.
Set up webhooks
To get a webhook notification when your task completes, specify the webhook_url in the body of your task creation request, as shown in the HTTP example below:
http
curl -X POST https://api.vmodel.ai/api/tasks/v1/create
-H "Authorization: Bearer $VModel_API_TOKEN"
-H "Content-Type: application/json"
-d '{
"version": "a3c8d261fd14126eececf9812b52b40811e9ed557ccc5706452888cdeeebc0b6",
"webhook_url": "https://example.com/vmodel-webhook",
"input": {
"swap_image": "https://data.vmodel.ai/data/model-example/vmodel/photo-face-swap-pro/swap_image.png",
"target_image": "https://vmodel.ai/data/model/vmodel/photo-face-swap-pro/target_image.png",
"disable_safety_checker": false
}
}'
Receive webhooks
The webhook request body is a JSON object. Its structure is identical to the response from the Check Task API. Below is an example of a successful task payload:
json
{
"task_id": "d9opjevn1bd48r5czq",
"user_id": 1,
"version": "85e248d268bcc04f5302cf9645663c2c12acd03c953ec1a4bbfdc252a65bddc0",
"error": "",
"total_time": 3.0,
"predict_time": 3.0,
"logs": "",
"output": ["https://vmodel.ai/data/model/vmodel/photo-face-swap-pro/target_image.png"],
"status": "succeeded",
"create_at": 1746497063,
"completed_at": null
}
Refer to Task status for the list of possible status values.
- succeeded: the Task completed successfully.
- failed: the Task encountered an error during processing.
Here’s an example of a webhook handler(python fastapi):
python
class VmodelWebhookDTO(BaseModel):
task_id: Union[str, None] = None
user_id: Union[int, None] = None
version: Union[str, None] = None
error: Union[Any, None] = None
total_time: Union[Any, None] = None
predict_time: Union[Any, None] = None
logs: Union[str, None] = None
output: Union[Any, None] = None
status: Union[str, None] = None
create_at: Union[int, None] = None
completed_at: Union[int, None] = None
@router.post(path="/webhook/vmodel")
def vmodel_webhook(request: Request, webhook_data: VmodelWebhookDTO):
return demohandler.vmodel_webhook(request=request, webhook_data=webhook_data)
Retries
To ensure reliable notification delivery, we have designed an automatic retry mechanism. When Vmodel sends a webhook to your endpoint, we will automatically trigger a retry if the request fails due to a network issue or if we receive a 4xx/5xx HTTP response code.
Retries are performed multiple times using an exponential backoff algorithm, and the entire retry cycle will conclude approximately 1 minute after the task has completed.
Idempotency
Please design your webhook handlers to be idempotent. As the same event may be sent more than once, your handler must be able to correctly identify and manage duplicate requests to avoid unintended consequences.