Webhook Callbacks

Overview

PixVerse can send task-status updates to your callback URL whenever the status of a video-generation task changes. Webhooks reduce the need for frequent status polling.

Supported Capabilities

Capability	Endpoint	Webhook support
Text-to-Video	`/openapi/v2/video/text/generate`	Yes
Image-to-Video	`/openapi/v2/video/img/generate`	Yes
First and Last Frame	`/openapi/v2/video/transition/generate`	Yes
Lipsync	`/openapi/v2/video/lip_sync/generate`	Yes
Video Extend	`/openapi/v2/video/extend/generate`	Yes
Sound Effect	`/openapi/v2/video/sound_effect/generate`	Yes
Reference-to-Video (Fusion)	`/openapi/v2/video/fusion/generate`	Yes
Multi-Transition Video	`/openapi/v2/video/multi_transition/generate`	Yes
Subject Replacement (Swap)	`/openapi/v2/video/swap/generate`	Yes
Video Restyle	`/openapi/v2/video/restyle/generate`	Yes
Motion Control	`/openapi/v2/video/mimic/generate`	Yes
Video Edit (Modify)	`/openapi/v2/video/modify/generate`	Yes
Video Upscale	`/openapi/v2/video/upscale/generate`	Yes

Integration Steps

1. Create a `webhook_id`

Open the Webhook management page, register an HTTPS callback URL, and obtain a webhook_id and Secret Key.

2. Add `webhook_id` to a generation request

Pass the configured webhook_id in the request body. The following example uses Text-to-Video:

{
  "aspect_ratio": "16:9",
  "duration": 5,
  "model": "v6",
  "prompt": "A calm evening at a suburban bus station with soft neon lights.",
  "quality": "720p",
  "webhook_id": "1234"
}

3. Verify each callback and return `ok`

Verify the signature headers and request body before processing the callback. After successful verification and receipt, return HTTP 200 with the plain-text body ok.

Callback Request

HTTP Method

POST

Request Headers

Header	Type	Description
`Webhook-Timestamp`	string	Unix timestamp in seconds.
`Webhook-Nonce`	string	32-character random lowercase alphanumeric string.
`Webhook-Signature`	string	Base64-encoded HMAC-SHA256 signature.
`Ai-trace-id`	string	Request identifier for tracing and troubleshooting.
`Content-Type`	string	Fixed value: `application/json`.

Request Body

The callback body contains the current task result. Fields may vary by task status and capability.

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

For the authoritative meaning of task states, see Query Task Status. Do not treat HTTP delivery alone as generation success; check the callback status value.

Signature Verification

1. Construct the signing string

Join the timestamp, nonce, and URL-encoded payload with newline characters:

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

timestamp: value of the Webhook-Timestamp header

nonce: value of the Webhook-Nonce header

url_encoded_payload: request-body fields sorted by key and encoded as a query string

2. URL-encode the payload

Convert each JSON field to key=value, sort fields alphabetically by key, and join them with &.

Original payload:

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

Encoded payload:

has_audio=true&id=123456789&status=1&url=https%3A%2F%2Fexample.com%2Fvideo.mp4

3. Calculate the signature

Use the webhook Secret Key to calculate an HMAC-SHA256 digest, then Base64-encode it:

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

Compare the result with the Webhook-Signature header using a timing-safe comparison function.

Python Verification Example

Response Requirements

Item	Required value
HTTP status	`200`
Response body	`ok`

Example:

If the callback endpoint returns a non-200 status or a body other than ok, PixVerse retries delivery.

Retry Policy

Retry	Delay
First	2 seconds
Second	10 seconds
Third	30 seconds
Fourth	1 minute
Fifth	5 minutes
Sixth	15 minutes
Seventh	1 hour
Eighth	4 hours

Each retry interval may include up to +/-10% jitter. After the final retry, the delivery is marked as failed.

Security Recommendations

Always verify the signature before processing business logic.

Reject stale Webhook-Timestamp values, for example timestamps outside a five-minute window, to reduce replay risk.

Use HTTPS for the callback URL.

Store the Secret Key securely and never expose it in client-side code or version control.

Use timing-safe comparison functions such as hmac.compare_digest.

Process callbacks idempotently because the same event may be delivered more than once.

Troubleshooting

Symptom	Check
Signature mismatch	Confirm the exact raw field values, alphabetical key ordering, URL encoding, newline separators, and Secret Key.
Repeated callbacks	Confirm that the endpoint returns HTTP `200` and the exact body `ok`.
Missing callbacks	Confirm the `webhook_id`, callback URL accessibility, HTTPS certificate, and firewall rules.
Duplicate processing	Deduplicate by task ID and status before applying business changes.

Overview#

Supported Capabilities#

Integration Steps#

1. Create a webhook_id#

2. Add webhook_id to a generation request#

3. Verify each callback and return ok#

Callback Request#

HTTP Method#

Request Headers#

Request Body#

Signature Verification#

1. Construct the signing string#

2. URL-encode the payload#

3. Calculate the signature#

Python Verification Example#

Response Requirements#

Retry Policy#

Security Recommendations#

Troubleshooting#