Callback Delivery for Files Over 4.5 MB

Use this guide when your automation needs to return large files that exceed the 4.5 MB request body limit enforced at our API edge. The direct-upload flow keeps the callback payload lightweight while preserving the same fields your existing integrations expect.

Direct-upload flow (over 4.5 MB)

Step 1: POST /api/orders/callback/prepare to get signed upload URL(s) and object_key. This reserves the upload slots and returns signed URLs.

Step 2: PUT <signed_upload_url> with the file bytes. This performs the actual file uploads to secure storage.

Step 3: POST /api/orders/callback with your normal payload, referencing each object_key. After all uploads succeed, this sends the callback to complete the order.

Why this matters

• Avoids the request size limit by uploading files straight to secure storage.
• Works alongside the existing base64 and hosted URL options—no breaking changes.
• Keeps delivery instant: once you callback, the buyer receives the file immediately.

When to use direct upload

You need to send any single file larger than 4.5 MB.
You want to bundle multiple files without worrying about the combined payload size.
Your automation prefers streaming binary data instead of encoding it as base64.

For smaller payloads you can keep using base64 or hosted URLs exactly as before—those paths are unchanged.

Callback payload basics

The callback schema is the same one documented in the standard guide. For large uploads, add object_key inside each files entry (alongside filename and mime_type) so the platform can fetch the binary you uploaded.

Prerequisites

Callback URL and x-callback-secret from the Connect step.
Ability to make HTTPS POST and PUT requests from your automation platform.
Filename, MIME type, and file size available before uploading the binary content.

Single Large File

Use this flow when you need to upload one large file that exceeds 4.5 MB.

Step 1: Prepare request

Call the prepare endpoint before uploading. Include your callback secret and file descriptor.

Endpoint: POST /api/orders/callback/prepare
Headers: Content-Type: application/json, x-callback-secret: YOUR_SECRET

{
  "order_id": "order-uuid",
  "filename": "final-video.mp4",
  "mime_type": "video/mp4",
  "file_size": 9328475
}

The response returns everything you need to upload:

{
  "ok": true,
  "order_id": "order-uuid",
  "is_test_mode": false,
  "filename": "20241109-ab12cd-final-video.mp4",
  "object_key": "orders/order-uuid/20241109-ab12cd-final-video.mp4",
  "upload_url": "https://SIGNED_UPLOAD_URL",
  "requires_headers": {
    "Content-Type": "video/mp4"
  },
  "expires_in": 3600,
  "max_bytes": 157286400
}

object_key is the identifier you will send later in the callback payload.
upload_url is a one-time, short-lived link that accepts the binary upload.
requires_headers contains any headers you must include in the PUT request.

Step 2: PUT the binary file

Perform an HTTP PUT directly to the signed upload_url. Send the raw bytes of the file as the body and include any required headers (at minimum Content-Type).

PUT https://SIGNED_UPLOAD_URL
Content-Type: video/mp4
Content-Length: 9328475

<binary file content>

On success you will receive a 200 response from our secure storage layer. If the upload fails, retry the PUT (you do not need to call prepare again unless the signed URL expires).

Automation tooling tips

• n8n: use an HTTP Request node in PUT mode and send the binary data directly.
• Make.com: use an HTTP module with "Upload a file" setting.
• Custom code: pass the binary buffer/stream to your HTTP client—no need to base64 encode the file.

Step 3: Final callback

Once the upload succeeds, send your normal callback payload and reference the uploaded file using theobject_key. This keeps output types consistent with legacy behaviour.

⚠️ Important: These are template examples. Replace all placeholders with real values:
• order-uuid → Use the actual order_id from your webhook payload
• object_key → Use the exact object_key returned by the prepare endpoint
• Include the x-callback-secret header in your request (see cURL example below)

Examples

Video file:

{
  "ok": true,
  "order_id": "order-uuid",
  "output_type": "video",
  "files": [
    {
      "object_key": "orders/order-uuid/20241109-ab12cd-final-video.mp4",
      "filename": "final-video.mp4",
      "mime_type": "video/mp4"
    }
  ]
}

PDF document:

{
  "ok": true,
  "order_id": "order-uuid",
  "output_type": "file",
  "files": [
    {
      "object_key": "orders/order-uuid/20241109-ab12cd-report.pdf",
      "filename": "report.pdf",
      "mime_type": "application/pdf"
    }
  ]
}

Image file:

{
  "ok": true,
  "order_id": "order-uuid",
  "output_type": "file",
  "files": [
    {
      "object_key": "orders/order-uuid/20241109-ab12cd-chart.png",
      "filename": "chart.png",
      "mime_type": "image/png"
    }
  ]
}

Excel spreadsheet:

{
  "ok": true,
  "order_id": "order-uuid",
  "output_type": "xlsx",
  "files": [
    {
      "object_key": "orders/order-uuid/20241109-ab12cd-data.xlsx",
      "filename": "data.xlsx",
      "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
    }
  ]
}

Audio file:

{
  "ok": true,
  "order_id": "order-uuid",
  "output_type": "file",
  "files": [
    {
      "object_key": "orders/order-uuid/20241109-ab12cd-audio.mp3",
      "filename": "audio.mp3",
      "mime_type": "audio/mpeg"
    }
  ]
}

Testing with cURL

curl -X POST "https://api.example.com/api/orders/callback" \
  -H "Content-Type: application/json" \
  -H "x-callback-secret: your-callback-secret" \
  -d '{
    "ok": true,
    "order_id": "test-order-uuid",
    "output_type": "video",
    "files": [
      {
        "object_key": "orders/test-order-uuid/20241109-ab12cd-final-video.mp4",
        "filename": "final-video.mp4",
        "mime_type": "video/mp4"
      }
    ]
  }'

Required fields

ok: Must be true for success
order_id: UUID from the original webhook payload
output_type: One of text, csv, json, file, url, xlsx, video
files: Array with at least one file object

File object fields

object_key: Required. The identifier returned by the prepare endpoint
filename: Required. The display name for the file
mime_type: Required. The MIME type of the file (e.g., video/mp4, application/pdf)

Allowed MIME types

Complete list of supported MIME types for callback files:

Text and Data

text/plain: Plain text reports
text/csv: CSV data files
application/json, text/json: JSON data

Documents

application/pdf: PDF documents
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: Excel files (XLSX)
application/vnd.openxmlformats-officedocument.wordprocessingml.document: Word documents (DOCX)

Images

image/jpeg: JPEG images
image/png: PNG images
image/webp: WebP images

Video

video/mp4: MP4 video
video/quicktime: MOV video
video/webm: WebM video
video/x-msvideo: AVI video

Audio

audio/mpeg: MP3 audio
audio/wav: WAV audio
audio/aac: AAC audio
audio/ogg: OGG audio

Keep your output type

Always set output_type to the value you want the buyer to see (for example video, file, xlsx). The platform now preserves your original type even when ingesting files from secure storage.

Error handling & retries

Prepare 400/401/404/409: verify the order ID, callback secret, and that the order is still in progress. 404 indicates the order was not found.
Prepare 413: file exceeds the server-side limit shown in max_bytes.
PUT failures: retry the upload. If the signed URL expires, call prepare again for a fresh link.
Callback validation errors: ensure the object_key matches the one returned by prepare. The platform validates file size automatically after downloading the file.

Testing checklist

Run the prepare call and confirm you receive ok: true and an object_key.
Upload a sample file and verify the PUT returns 200.
Send the final callback and check the order status flips to delivered instantly.
Download the file from the SellerShorts dashboard to confirm the output type and filename display correctly.

Polling (optional)

Using polling instead of callbacks? The same object_key fields work there too—just include them in your polling response. For the full schema and examples, see Polling (Integration guide).

Callback Delivery for Files Over 4.5 MB

Direct-upload flow (over 4.5 MB)

Step 1: POST /api/orders/callback/prepare to get signed upload URL(s) and object_key. This reserves the upload slots and returns signed URLs.

Step 2: PUT <signed_upload_url> with the file bytes. This performs the actual file uploads to secure storage.

Step 3: POST /api/orders/callback with your normal payload, referencing each object_key. After all uploads succeed, this sends the callback to complete the order.

Why this matters

• Avoids the request size limit by uploading files straight to secure storage.
• Works alongside the existing base64 and hosted URL options—no breaking changes.
• Keeps delivery instant: once you callback, the buyer receives the file immediately.

When to use direct upload

You need to send any single file larger than 4.5 MB.
You want to bundle multiple files without worrying about the combined payload size.
Your automation prefers streaming binary data instead of encoding it as base64.

For smaller payloads you can keep using base64 or hosted URLs exactly as before—those paths are unchanged.

Callback payload basics

Prerequisites

Callback URL and x-callback-secret from the Connect step.
Ability to make HTTPS POST and PUT requests from your automation platform.
Filename, MIME type, and file size available before uploading the binary content.

Single Large File

Use this flow when you need to upload one large file that exceeds 4.5 MB.

Step 1: Prepare request

Call the prepare endpoint before uploading. Include your callback secret and file descriptor.

Endpoint: POST /api/orders/callback/prepare
Headers: Content-Type: application/json, x-callback-secret: YOUR_SECRET

{
  "order_id": "order-uuid",
  "filename": "final-video.mp4",
  "mime_type": "video/mp4",
  "file_size": 9328475
}

The response returns everything you need to upload:

{
  "ok": true,
  "order_id": "order-uuid",
  "is_test_mode": false,
  "filename": "20241109-ab12cd-final-video.mp4",
  "object_key": "orders/order-uuid/20241109-ab12cd-final-video.mp4",
  "upload_url": "https://SIGNED_UPLOAD_URL",
  "requires_headers": {
    "Content-Type": "video/mp4"
  },
  "expires_in": 3600,
  "max_bytes": 157286400
}

object_key is the identifier you will send later in the callback payload.
upload_url is a one-time, short-lived link that accepts the binary upload.
requires_headers contains any headers you must include in the PUT request.

Step 2: PUT the binary file

Perform an HTTP PUT directly to the signed upload_url. Send the raw bytes of the file as the body and include any required headers (at minimum Content-Type).

PUT https://SIGNED_UPLOAD_URL
Content-Type: video/mp4
Content-Length: 9328475

<binary file content>

On success you will receive a 200 response from our secure storage layer. If the upload fails, retry the PUT (you do not need to call prepare again unless the signed URL expires).

Automation tooling tips

• n8n: use an HTTP Request node in PUT mode and send the binary data directly.
• Make.com: use an HTTP module with "Upload a file" setting.
• Custom code: pass the binary buffer/stream to your HTTP client—no need to base64 encode the file.

Step 3: Final callback

Once the upload succeeds, send your normal callback payload and reference the uploaded file using theobject_key. This keeps output types consistent with legacy behaviour.

Examples

Video file:

{
  "ok": true,
  "order_id": "order-uuid",
  "output_type": "video",
  "files": [
    {
      "object_key": "orders/order-uuid/20241109-ab12cd-final-video.mp4",
      "filename": "final-video.mp4",
      "mime_type": "video/mp4"
    }
  ]
}

PDF document:

{
  "ok": true,
  "order_id": "order-uuid",
  "output_type": "file",
  "files": [
    {
      "object_key": "orders/order-uuid/20241109-ab12cd-report.pdf",
      "filename": "report.pdf",
      "mime_type": "application/pdf"
    }
  ]
}

Image file:

{
  "ok": true,
  "order_id": "order-uuid",
  "output_type": "file",
  "files": [
    {
      "object_key": "orders/order-uuid/20241109-ab12cd-chart.png",
      "filename": "chart.png",
      "mime_type": "image/png"
    }
  ]
}

Excel spreadsheet:

{
  "ok": true,
  "order_id": "order-uuid",
  "output_type": "xlsx",
  "files": [
    {
      "object_key": "orders/order-uuid/20241109-ab12cd-data.xlsx",
      "filename": "data.xlsx",
      "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
    }
  ]
}

Audio file:

{
  "ok": true,
  "order_id": "order-uuid",
  "output_type": "file",
  "files": [
    {
      "object_key": "orders/order-uuid/20241109-ab12cd-audio.mp3",
      "filename": "audio.mp3",
      "mime_type": "audio/mpeg"
    }
  ]
}

Testing with cURL

curl -X POST "https://api.example.com/api/orders/callback" \
  -H "Content-Type: application/json" \
  -H "x-callback-secret: your-callback-secret" \
  -d '{
    "ok": true,
    "order_id": "test-order-uuid",
    "output_type": "video",
    "files": [
      {
        "object_key": "orders/test-order-uuid/20241109-ab12cd-final-video.mp4",
        "filename": "final-video.mp4",
        "mime_type": "video/mp4"
      }
    ]
  }'

Required fields

ok: Must be true for success
order_id: UUID from the original webhook payload
output_type: One of text, csv, json, file, url, xlsx, video
files: Array with at least one file object

File object fields

object_key: Required. The identifier returned by the prepare endpoint
filename: Required. The display name for the file
mime_type: Required. The MIME type of the file (e.g., video/mp4, application/pdf)

Allowed MIME types

Complete list of supported MIME types for callback files:

Text and Data

text/plain: Plain text reports
text/csv: CSV data files
application/json, text/json: JSON data

Documents

application/pdf: PDF documents
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: Excel files (XLSX)
application/vnd.openxmlformats-officedocument.wordprocessingml.document: Word documents (DOCX)

Images

image/jpeg: JPEG images
image/png: PNG images
image/webp: WebP images

Video

video/mp4: MP4 video
video/quicktime: MOV video
video/webm: WebM video
video/x-msvideo: AVI video

Audio

audio/mpeg: MP3 audio
audio/wav: WAV audio
audio/aac: AAC audio
audio/ogg: OGG audio

Keep your output type

Always set output_type to the value you want the buyer to see (for example video, file, xlsx). The platform now preserves your original type even when ingesting files from secure storage.

Error handling & retries

Prepare 400/401/404/409: verify the order ID, callback secret, and that the order is still in progress. 404 indicates the order was not found.
Prepare 413: file exceeds the server-side limit shown in max_bytes.
PUT failures: retry the upload. If the signed URL expires, call prepare again for a fresh link.
Callback validation errors: ensure the object_key matches the one returned by prepare. The platform validates file size automatically after downloading the file.

Testing checklist

Run the prepare call and confirm you receive ok: true and an object_key.
Upload a sample file and verify the PUT returns 200.
Send the final callback and check the order status flips to delivered instantly.
Download the file from the SellerShorts dashboard to confirm the output type and filename display correctly.

Polling (optional)

Using polling instead of callbacks? The same object_key fields work there too—just include them in your polling response. For the full schema and examples, see Polling (Integration guide).

Callback Delivery for Files Over 4.5 MB

Direct-upload flow (over 4.5 MB)

Why this matters

When to use direct upload

Callback payload basics

Prerequisites

Single Large File

Step 1: Prepare request

Step 2: PUT the binary file

Automation tooling tips

Step 3: Final callback

Examples

Testing with cURL

Required fields

File object fields

Allowed MIME types

Text and Data

Documents

Images

Video

Audio

Archives

Keep your output type

Error handling & retries

Testing checklist

Polling (optional)

Callback Delivery for Files Over 4.5 MB

Direct-upload flow (over 4.5 MB)

Why this matters

When to use direct upload

Callback payload basics

Prerequisites

Single Large File

Step 1: Prepare request

Step 2: PUT the binary file

Automation tooling tips

Step 3: Final callback

Examples

Testing with cURL

Required fields

File object fields

Allowed MIME types

Text and Data

Documents

Images

Video

Audio

Archives

Keep your output type

Error handling & retries

Testing checklist

Polling (optional)