Webhook

What is Webhook

Token360 can POST to your HTTPS endpoint when an asynchronous job reaches a terminal state, so you do not have to poll continuously.

Use webhooks when your application needs to react in the background (update an order, persist output URLs, notify a 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.5",
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.

Video Callback Request