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 Tool 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 AI Agent automation
Security: Prevents unauthorized result submissions
Configuration: Set during the Connect step of AI Tool 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
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.
sellershorts