Skip to main content

Callback Delivery

After your AI automation processes an order, you must send the results back to SellerShorts using our callback endpoint. This completes the order and delivers results to the buyer.

Overview

Callback delivery is required for all AI Shorts using async processing. Your automation receives inputs via webhook, processes them, then POSTs results to our callback URL to complete the order.

Callback endpoint

All callback requests must be sent to your Callback URL shown in-app.

  • Method: POST only
  • Content-Type: application/json
  • Required header: x-callback-secret: your-secret
  • Authentication: The callback secret you configured in the Connect step

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

Payload formats

Version 1 (v1) - Single output format

Simple format for single results or file outputs:

Success with text result

{
  "ok": true,
  "order_id": "order-uuid-from-webhook",
  "output_type": "text",
  "result_text": "Your analysis results go here..."
}

Success with file result

{
  "ok": true,
  "order_id": "order-uuid-from-webhook",
  "output_type": "file",
  "file_base64": "base64-encoded-file-content",
  "filename": "report.pdf",
  "mime_type": "application/pdf"
}

Success with hosted URL

{
  "ok": true,
  "order_id": "order-uuid-from-webhook",
  "output_type": "url",
  "result_url": "https://your-storage.com/path/to/result.pdf"
}

Success with multiple files (v1)

{
  "ok": true,
  "order_id": "order-uuid-from-webhook",
  "output_type": "file",
  "files": [
    {
      "filename": "summary.txt",
      "mime_type": "text/plain",
      "file_base64": "base64-content-1"
    },
    {
      "filename": "data.csv",
      "mime_type": "text/csv",
      "file_base64": "base64-content-2"
    }
  ]
}

Failure response

{
  "ok": false,
  "order_id": "order-uuid-from-webhook",
  "error_code": "processing_failed",
  "error_message": "Unable to analyze the provided URL",
  "retryable": false,
  "diagnostics": {
    "attempted_url": "https://example.com",
    "error_details": "Connection timeout after 30 seconds"
  }
}

Version 2 (v2) - Multi-output format (recommended)

Advanced format supporting multiple outputs and partial delivery:

Complete success with multiple outputs

{
  "ok": true,
  "api_version": "2",
  "order_id": "order-uuid-from-webhook",
  "status": "complete",
  "idempotency_key": "unique-request-id-123",
  "outputs": [
    {
      "filename": "analysis-report.html",
      "content_type": "text/html",
      "file_base64": "base64-html-content",
      "rank": 1,
      "variant": "primary",
      "metadata": {
        "title": "SEO Analysis Report",
        "pages_analyzed": 15
      }
    },
    {
      "filename": "recommendations.csv",
      "content_type": "text/csv",
      "url": "https://your-storage.com/recs.csv",
      "rank": 2,
      "variant": "data",
      "metadata": {
        "recommendations_count": 23
      }
    }
  ]
}

Partial delivery

{
  "ok": true,
  "api_version": "2",
  "order_id": "order-uuid-from-webhook",
  "status": "partial",
  "idempotency_key": "delivery-1-of-3",
  "outputs": [
    {
      "filename": "preliminary-analysis.txt",
      "content_type": "text/plain",
      "file_base64": "base64-text-content",
      "rank": 1,
      "metadata": {
        "stage": "preliminary",
        "completion_percent": 30
      }
    }
  ]
}

Output types and fields

Required fields (all versions)

  • ok: true for success, false for failure
  • order_id: UUID from the original webhook payload

Success fields (v1)

  • output_type: One of text, html, json, csv, file, xlsx, url
  • result_text: For text, HTML, JSON, CSV content
  • result_url: For hosted files or external resources
  • file_base64: Base64-encoded file content
  • filename: Required with file_base64
  • mime_type: Required with file_base64
  • files: Array for multiple files

Success fields (v2)

  • api_version: Must be "2"
  • status: "partial" or "complete" (default: complete)
  • idempotency_key: Unique identifier for safe retries (optional)
  • outputs: Array of output objects (minimum 1)

Output object fields (v2)

  • filename: Display name for the output
  • content_type: MIME type (e.g., "text/html", "text/csv")
  • file_base64: Base64 content (mutually exclusive with url)
  • url: Hosted file URL (mutually exclusive with file_base64)
  • bytes: File size in bytes (optional)
  • rank: Display order (optional, integer)
  • variant: Output variant identifier (optional)
  • metadata: Additional key-value data (optional)

Error fields

  • error_code: Machine-readable error identifier
  • error_message: Human-readable error description
  • retryable: Whether the order can be retried (optional)
  • diagnostics: Additional debugging information (optional)

File handling

Base64 encoding

  • Overhead: Base64 adds ~33% to file size
  • Limit: Total payload should stay under ~75MB
  • Encoding: Use standard base64 encoding without line breaks
  • Alternative: Use URL hosting for large files

URL hosting

  • Accessibility: URLs must be publicly accessible
  • Lifetime: URLs should remain valid for at least 30 days
  • HTTPS: Use HTTPS URLs for security
  • Headers: No authentication headers required for hosted files

MIME types

Common MIME types for different output formats:

  • text/plain: Plain text reports
  • text/html: Formatted HTML reports
  • text/csv: CSV data files
  • application/json: JSON data
  • application/pdf: PDF documents
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: Excel files
  • image/png: PNG images
  • image/jpeg: JPEG images

Error handling

Common error codes

  • processing_failed: General processing error
  • invalid_input: Input data was invalid or unusable
  • timeout: Processing took too long
  • quota_exceeded: Rate limit or usage limit reached
  • service_unavailable: External service dependency failed
  • auth_failed: Authentication with external service failed

Retry guidance

  • Retryable errors: timeouts, service unavailable, temporary failures
  • Non-retryable errors: invalid input, authentication failures, quota exceeded
  • Retry timing: Use exponential backoff for retries
  • Max retries: Limit to 3-5 retry attempts

Testing callback delivery

cURL examples

Text result

curl -X POST "https://api.example.com/callback" \
  -H "Content-Type: application/json" \
  -H "x-callback-secret: your-callback-secret" \
  -d '{
    "ok": true,
    "order_id": "test-order-uuid",
    "output_type": "text",
    "result_text": "Analysis completed successfully..."
  }'

File result

curl -X POST "https://api.example.com/callback" \
  -H "Content-Type: application/json" \
  -H "x-callback-secret: your-callback-secret" \
  -d '{
    "ok": true,
    "order_id": "test-order-uuid",
    "output_type": "file",
    "file_base64": "SGVsbG8gV29ybGQ=",
    "filename": "hello.txt",
    "mime_type": "text/plain"
  }'

Best practices

  • Include order_id – Always include the exact order_id from webhook payload
  • Use v2 for complex outputs – v2 format provides more flexibility
  • Handle large files via URL – Host large files and provide URLs instead of base64
  • 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

💡 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 - AI Shorts Marketplace | Specialized Selling Automation