Callback Basics
This page covers the fundamental concepts and requirements for callback delivery that apply to all callback scenarios. For specific payload formats, see the callback guides below.
Overview
Callback delivery is required for all AI Shorts. Your automation receives inputs via webhook, processes them, then POSTs results to our callback URL to complete the order.
Required fields
Every callback must include these fields:
- ok:
true for success, false for failure - order_id: UUID from the original webhook payload
Note: While the webhook payload includes short_id, you only need order_id for callbacks. The order_id uniquely identifies the specific order.
Success and failure callbacks
Callbacks can report either success or failure:
- Success callbacks – Send
ok: true with your results (text, files, URLs, etc.) - Failure callbacks – Send
ok: false with error details if processing fails
Both types require the same order_id and x-callback-secret header.
⚠️ Large file notice
Callback requests pass through a 4.5 MB body limit. If your payload (for example, videos or multiple attachments) will be larger, switch to the direct-upload flow described in Callback (Over 4.5 MB). Files under the limit can follow the Callback (Under 4.5 MB) guide.
Callback endpoint
All callback requests must be sent to your Callback URL provided during the Connect step of AI Short submission.
- Method: POST only
- Content-Type:
application/json - Required header:
x-callback-secret: your-secret - Authentication: The callback secret you configured in the Connect step
Response codes
Your callback will receive one of these HTTP status codes:
- 200 OK – Callback processed successfully (or duplicate safely ignored)
- 400 Bad Request – Invalid payload, order not found, or validation error
- 401 Unauthorized – Missing or invalid x-callback-secret header
- 413 Payload Too Large – File exceeds size limit for its type
- 500 Internal Server Error – Platform processing error (safe to retry)
Required callback header
Every callback request must include your callback secret in the header:
x-callback-secret: your-callback-secret-value
- Purpose: Verifies the callback comes from your automation
- Security: Prevents unauthorized result submissions
- Configuration: Set during the Connect step of AI Short submission
- Management: Can be regenerated if compromised
Idempotency & duplicate handling
The callback endpoint is automatically idempotent - it's safe to send callbacks multiple times:
- Duplicate protection – Callbacks for already-completed orders return 200 OK without reprocessing
- Safe retries – Network failures? Retry freely without risk of duplicate delivery
- No side effects – Duplicate callbacks don't affect order status or buyer experience
- Automatic handling – Platform tracks order state and ignores redundant submissions
Best practices
- Include order_id – Always include the exact order_id from webhook payload
- Use v2 for multiple outputs or partial delivery – v2 format supports multiple files and incremental delivery
- For large files, use direct upload (object_key) or hosted URLs instead of base64 – Avoids size limits and encoding overhead
- Validate before sending – Check JSON structure and required fields
- Monitor callback success – Log callback responses to track delivery success
- Implement retries – Retry failed callbacks with exponential backoff (safe due to idempotency)
💡 Callback timing
Send callbacks as soon as processing is complete. Buyers are waiting for results, and faster delivery improves their experience. Don't batch or delay callback delivery unnecessarily.