Webhook

What is Webhook

Token360 can notify your service when an asynchronous video generation task finishes, so your application does not need to continuously poll the video status endpoint.

Webhook lets you provide a callback_url when creating a video task with POST /v1/videos. When the task reaches a terminal state, Token360 sends an HTTP POST request to your callback URL with the final task status and video payload.

Use webhooks when your application needs to react to completed or failed video jobs in the background, such as updating an order, saving a generated video URL, or notifying an end user.

How to Enable Webhook

When calling POST /v1/videos, include two fields:

• callback_url: your HTTPS endpoint that receives the POST callback.
• request_id: your business ID, such as an order ID. Token360 echoes this value in the callback envelope so you can match the callback to your local record.

1curl -X POST https://api.token360.ai/v1/videos \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "seedance-2.0-fast",
6    "prompt": "A paper crane unfolds into a real bird and flies away.",
7    "resolution": "480p",
8    "duration": 5,
9    "aspect_ratio": "16:9",
10    "generate_audio": false,
11    "callback_url": "https://your-app.example.com/webhooks/video",
12    "request_id": "your-order-id-001"
13  }'

If callback_url is omitted, no callback fires and you must poll GET /v1/videos/{video_id} yourself.

When the Callback Fires

• Token360 sends the callback once when the video task reaches a terminal state: completed or failed.
• Intermediate states, such as queued and in_progress, do not trigger callbacks.
• A given video task delivers at most one successful callback. If all delivery attempts fail, Token360 gives up.

Retry and Timeout

• Per-attempt timeout: 30 seconds.
• Maximum attempts: 3 total attempts, including the first delivery.
• Retry backoff intervals: 1 second before the second attempt, then 3 seconds before the third attempt.
• Any 2xx response stops retrying and marks delivery as successful.
• After following redirects, any final non-2xx response triggers a retry. A redirect chain that resolves to 2xx is treated as successful.
• After 3 failed attempts, Token360 gives up and does not redeliver. Use GET /v1/videos/{video_id} to recover the final state if needed.

Idempotency

• A given video task id delivers at most one successful callback.
• If you reuse the same request_id across multiple video tasks, each task can still deliver its own callback.
• Network conditions may still produce rare duplicate deliveries during retry.
• Implement your endpoint idempotently, for example by deduplicating on id and status.

Query callback_url