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.

📚 Callback Guides

Choose the guide that matches your file size:

• Callback (Under 4.5 MB) - For payloads under 4.5 MB
• Callback (Over 4.5 MB) - For large files using direct upload

Overview

Callback delivery is required for all AI Tools.

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
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.