Callback Delivery (Under 4.5 MB)

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.

Payload formats

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

{
  "ok": true,
  "order_id": "order-uuid-from-webhook",
  "output_type": "json",
  "result_text": "{\"status\": \"success\", \"data\": [1, 2, 3]}"
}

{
  "ok": true,
  "order_id": "order-uuid-from-webhook",
  "output_type": "csv",
  "result_text": "Name,Age,City\nJohn,30,New York\nJane,25,Los Angeles"
}

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..."
  }'

Apply to Amazon (structured_output envelope)

If your AI Tool declared write verbs in the Inputs step wizard's "Post to Amazon (Optional)" section, the order detail page can render a one-click Apply to Amazon button that pushes your tool's output directly to the buyer's connected Amazon account.

For that button to appear, your v2 callback (api_version: "2") must include a structured_output object inside the metadata of at least one output. This works with any output shape: a single base64 file, multiple files, or a hosted URL. The shape is the same regardless of which Amazon provider you target; only the action and provider change.

Example 1: Amazon Seller Central (listings.update)

This example would be returned by Tool 1 (Listing Fixer) after the agent generates a new title and bullets. When the buyer clicks Apply, the broker calls listings.update with the payload object.

{
  "ok": true,
  "api_version": "2",
  "order_id": "order-uuid-from-webhook",
  "status": "complete",
  "outputs": [
    {
      "filename": "listing-rewrite.json",
      "content_type": "application/json",
      "file_base64": "base64-json-content",
      "rank": 1,
      "metadata": {
        "structured_output": {
          "action": "listings.update",
          "provider": "amazon",
          "payload": {
            "sku": "ABC-123",
            "title": "New title here",
            "bullets": ["Bullet 1", "Bullet 2"]
          },
          "confirm": {
            "summary": "Update title and bullets for SKU ABC-123",
            "diff_preview": {
              "before": { "title": "Old title" },
              "after":  { "title": "New title here" }
            }
          }
        }
      }
    }
  ]
}

Example 2: Amazon Ads (ads.sb.campaigns.create)

This example would be returned by Tool 2 (Ad Campaign Builder) after the agent designs a new Sponsored Brands campaign. When the buyer clicks Apply, the broker calls ads.sb.campaigns.create with the payload object.

{
  "ok": true,
  "api_version": "2",
  "order_id": "order-uuid-from-webhook",
  "status": "complete",
  "outputs": [
    {
      "filename": "campaign-plan.json",
      "content_type": "application/json",
      "file_base64": "base64-json-content",
      "rank": 1,
      "metadata": {
        "structured_output": {
          "action": "ads.sb.campaigns.create",
          "provider": "amazon_ads",
          "payload": {
            "name": "Holiday 2026 SB Campaign",
            "daily_budget": 50,
            "start_date": "20261201",
            "end_date": "20261231",
            "ad_format": "productCollection",
            "state": "paused"
          },
          "confirm": {
            "summary": "Create Sponsored Brands campaign 'Holiday 2026 SB Campaign' with $50/day budget",
            "diff_preview": {
              "before": { "status": "no campaign yet" },
              "after":  { "name": "Holiday 2026 SB Campaign", "daily_budget": 50 }
            }
          }
        }
      }
    }
  ]
}

structured_output fields (same for both providers)

• action: Required. The broker verb to invoke when the buyer clicks Apply. Must match a write verb you declared in the wizard.
  • Amazon Seller Central verbs: "listings.update", "listings.update_images", "listings.a_plus_generate", "messaging.request_review"
  • Amazon Ads verbs: "ads.campaigns.create", "ads.keywords.update", "ads.negative_keywords.create", "ads.sb.campaigns.create", "ads.sb.keywords.create", "ads.sb.negative_keywords.create", "ads.sd.campaigns.create", "ads.sd.ad_groups.create", "ads.sd.product_ads.create", "ads.sd.targets.create", "ads.sd.negative_targets.create"
• provider: Required. Must match the verb's provider.
  • "amazon" for Amazon Seller Central verbs (the listings.*, messaging.* verbs)
  • "amazon_ads" for Amazon Ads verbs (everything starting with ads.*)
• payload: Required. The exact parameter object that will be sent to the broker capability when the buyer clicks Apply. The field names and shape must match the broker's validation schema for that verb.
  • For Amazon Seller Central verb schemas, see the Amazon Seller Central guide.
  • For Amazon Ads verb schemas, see the Amazon Ads guide.
• confirm.summary: Optional. A one-line human-readable summary shown to the buyer in the confirmation modal (e.g., "Update title and bullets for SKU ABC-123"). If omitted, a generic fallback like "This will perform 'listings.update' on your connected Amazon account" is shown.
• confirm.diff_preview.before: Optional. Any JSON object representing the current state. Shown side-by-side with after in the modal's collapsible "View change preview" panel.
• confirm.diff_preview.after: Optional. Any JSON object representing the proposed state.

When the Apply button renders

The order detail page renders the Apply button when these four checks all pass (verified in src/app/orders/[id]/page.tsx):

1. The order's apply_actions array has at least one entry with show_button: true. (Populated at dispatch time from what you declared and toggled ON in the wizard.)
2. The order is not in revision-delivery mode.
3. At least one of the order's output files has a metadata.structured_output object.
4. That structured_output.action + provider matches one of the declared apply_actions entries.

Two additional end-to-end prerequisites are not strictly button-render checks but the button won't be useful without them:

• Admin must have approved your tool. Tools that declare write verbs require an explicit acknowledgement checkbox from admin before approval.
• The buyer must have a connected Amazon account for the verb's provider (Seller Central for amazon verbs, Amazon Ads for amazon_ads verbs). If they don't, the broker call when the buyer clicks Apply will return an authorization error.

Important caveats

• v2 required. The v1 callback schema has no metadata field, so the Apply button cannot work with v1. Use api_version: "2".
• Tested via your normal callback. No new endpoint or signing scheme. structured_output is just one more well-known key inside the existing per-output metadata bag.
• Field names matter. The broker validates payload against the verb's schema at click time. If field names use camelCase where the broker expects snake_case (e.g., "dailyBudget" instead of "daily_budget"), the broker call returns a validation error and the buyer sees "Apply failed" in the modal.
• You can attach multiple outputs. If your tool produces several files and only one carries a structured_output, the Apply button uses the newest output whose action matches a declared verb.
• Works with any output shape. The structured_output envelope can ride along with a base64 file, a hosted URL, or any other v2 output. You do not need to "send multiple files" to use it.