What is a Webhook?

A Webhook is used to notify your system when the status of a video generation task changes.
When the task status changes, the PixVerse AI API platform will automatically send the result back to your server.

Supported Features

Below is the list of features currently supported by Webhooks. More PixVerse AI API features will be supported in the future.

Feature (Endpoint)	Supported
`text-to-video video/text/generate`	✅
`image-to-video video/img/generate`	✅
`transition video/transition/generate`	✅
`lipsync video/lip_sync/generate`	✅
`extend video/extend/generate`	✅
`sound_effect video/sound_effect/generate`	✅
`fusion(reference to video) video/fusion/generate`	✅
`restyle video/restyle/generate`	✅
`multi_transition video/multi_transition/generate`	✅
`swap video/swap/generate`	✅
`restyle video/restyle/generate`	✅
`mimic video/mimic/generate`	✅
`modify video/modify/generate`	✅
`upscale video/upscale/generate`	✅

How to Use

Step 1: Create a webhook_id

Create a webhook_id by visiting the Webhook Management Page.

Step 2: Add webhook_id to the generation request

Step 3: Verify the webhook request and return ok

Webhook Signature Guide

Overview

To ensure the security and integrity of Webhook requests, all Webhook deliveries include signature information.
Clients should verify each request signature to prevent request forgery and data tampering.

Request Format

HTTP Method

POST

Content-Type

application/json

Request Headers

Header Name	Type	Description
`Webhook-Timestamp`	string	Unix timestamp (seconds)
`Webhook-Nonce`	string	32-character random string
`Webhook-Signature`	string	Request signature (Base64-encoded HMAC-SHA256)
`Ai-Trace-Id`	string	Request trace ID
`Content-Type`	string	Fixed value `application/json`

Request Body

Business data in JSON format. Example:

{
  "id": "123456789",
  "status": 1,
  "url": "https://example.com/video.mp4",
  "size": 10.5,
  "has_audio": true,
  "credits": 100
}

Signature Verification Algorithm

Step 1: Build the string to sign

The string to sign consists of three parts, joined by newline characters (\n):

{timestamp}\n{nonce}\n{url_encoded_payload}

Description:

timestamp: obtained from the Webhook-Timestamp header

nonce: obtained from the Webhook-Nonce header

url_encoded_payload: JSON body encoded as a URL query string

Step 2: URL-encode the payload

Convert each field in the JSON body into key=value format and join them with &.

Step 3: Generate the signature

Use HMAC-SHA256 with your Secret Key, then encode the result using Base64.

signature = Base64(HMAC-SHA256(secret_key, sign_string))

Step 4: Compare signatures

Compare the calculated signature with Webhook-Signature from the request headers.

Code Examples

Python

Go

Node.js

Java

Response Requirements

Successful Response

When the webhook is successfully received, you must return:

Item	Requirement
HTTP Status Code	`200`
Response Body	`ok` (lowercase, no extra characters)

Example

HTTP/1.1 200 OK
Content-Type: text/plain

ok

Failed Response

If the status code is not 200 or the body is not ok, the system will retry the webhook.

Retry Mechanism

If delivery fails, retries will be attempted with the following intervals:

Attempt	Interval
1	2 seconds
2	10 seconds
3	30 seconds
4	1 minute
5	5 minutes
6	15 minutes
7	1 hour
8	4 hours

Security Recommendations

Always verify the signature before processing logic.

Validate timestamps to prevent replay attacks.

Use HTTPS for webhook endpoints.

Store the Secret Key securely.

Use time-safe comparison functions.

Ensure idempotency by deduplicating events using id.

FAQ

Q: What should I do if signature verification fails?

Verify the Secret Key

Check URL encoding consistency

Confirm the string-to-sign format

Verify boolean value formatting (true / false)

If you have any other questions, please contact technical support.

Webhook integration

What is a Webhook?#

Supported Features#

How to Use#

Webhook Signature Guide#

Overview#

Request Format#

HTTP Method#

Content-Type#

Request Headers#

Request Body#

Signature Verification Algorithm#

Step 1: Build the string to sign#

Step 2: URL-encode the payload#

Step 3: Generate the signature#

Step 4: Compare signatures#

Code Examples#

Python#

Go#

Node.js#

Java#

Response Requirements#

Successful Response#

Failed Response#

Retry Mechanism#

Security Recommendations#

FAQ#

Q: What should I do if signature verification fails?#