If your platform expects a different JSON structure (e.g., OpenAI, Dialogflow, Vertex AI), you can define a custom payload template with placeholders. Expand the "Advanced: Custom Payload Template" section in the Connect step to access this feature.
⚠️ Important: Template Validation Required
If you use custom payload templates, you must test them with your actual platform before going live.
• Use the Test button to verify your platform accepts the payload
• Check your platform's webhook logs for errors
• Example templates are based on documentation and may need adjustments
• You are responsible for validating templates work with your platform
Outcome: After this step, SellerShorts can POST inputs to your webhook, and your automation can authenticate and send results back via callback.
The Connect step is where you link your AI automation to SellerShorts. You'll configure the webhook URL where we send buyer inputs and set up authentication to ensure secure communication.
Overview
When buyers run your AI Tool, we need to send their inputs to your automation and receive the results back. This step establishes the technical connection between SellerShorts and your automation platform.
Webhook payload with job_token (Amazon Ads)
If your AI Tool requires Amazon Ads (configured in the Inputs step), your webhook payload includes an additional job_token field:
The job_token is a secure token that allows your automation to make API calls to Amazon Ads on the buyer's behalf. Use it in the Authorization: Bearer {job_token} header when calling SellerShorts' capabilities API. The token stays valid for the entire workflow execution.
Outbound (SellerShorts → your webhook): Include your Authorization or x-api-key header
Inbound (your system → SellerShorts): Include x-callback-secret on the callback POST
Webhook URL
Protocol – Must use HTTPS (HTTP is not allowed for security)
Method – POST requests only
Format – Must accept application/json content type
Examples:
https://hook.make.com/abc123xyz
https://api.n8n.cloud/webhook/uuid
https://your-domain.com/api/webhook
Authentication headers
You must add at least one authentication header to verify requests come from SellerShorts:
Recommended patterns:
Authorization: Bearer YOUR_TOKEN – Best for OAuth/JWT/token services
x-api-key: YOUR_KEY – Best for static API keys/gateways
x-auth-token: YOUR_TOKEN – Alternative token header
Callback configuration
Quick overview
Callback is the recommended method for delivering results. Your automation POSTs results to our callback URL when processing is complete – providing instant delivery to buyers.
Callback URL: Displayed in-app during setup (where your automation sends results)
Callback Secret: Security header (x-callback-secret) to verify requests
Method: POST with JSON payload containing results and files
Delivery: Instant (as soon as your automation completes)
Big files? Use the optional direct-upload flow (prepare → PUT → callback) to handle files over 4.5 MB. See Callback Delivery (Over 4.5 MB Files) for the step-by-step guide.
📚 Complete callback documentation
Sending results under 4.5 MB? Follow the standard guide in Callback (Under 4.5 MB) for schema details, headers, and examples.
Working with larger files? Use the direct-upload walkthrough in Callback (Over 4.5 MB) to generate signed upload URLs and reference them in your callback.
Tip: You can also deliver large files by hosting them yourself and sending the URL output (Google Drive, Dropbox, etc.). That keeps the payload tiny with zero extra steps. See the Output step guide for a refresher on output types.
Polling URL (Alternative delivery method)
💡 Callback vs Polling
• Callback (recommended): Your automation POSTs results to us when complete – instant delivery
• Polling: We check your status endpoint every 15 minutes – simpler setup but slower
Quick overview
Polling is an alternative to callback for delivering results. Instead of POSTing results to us, we periodically check your status endpoint every 15 minutes.
When to use: Only if your automation cannot POST to our callback URL
Requirements: HTTPS GET endpoint with {order_id} placeholder
Response: JSON with status ("processing", "completed", or "failed")
Timing: Checked every 15 minutes, 8-second timeout per check
📚 Complete polling documentation
For detailed polling setup including response formats, file handling, timeouts, and best practices, see the Polling Delivery page in the Integrations section.
Payload configuration
Payload preview
Sample JSON – See exactly what we'll send to your webhook
Copy cURL – Get a complete cURL command for testing
Real data – Preview includes your actual input configuration
Custom Payload Template (Advanced)
Most platforms work with our default JSON payload format. However, if your automation platform requires a specific JSON structure (e.g., OpenAI, Dialogflow, custom APIs), you can define a custom payload template with placeholders.
💡 When to use custom templates
• Your platform expects a specific JSON structure that differs from our default
• You need to reorganize or rename fields for compatibility
• You want to combine multiple input fields into a single field
• You're integrating with APIs that have strict payload requirements
Available placeholders
{order_id}, {short_id}, {callback_url}, {ts}
{inputs.field_name} – Access any input field by its key name
{input_files}, {api_version} – For multi-file support
📚 Complete payload templates guide
For detailed template syntax, quoting rules, examples, platform compatibility, and troubleshooting, see the Payload Templates page in the Integrations section.
Connection testing
Required connection test
Before proceeding, you must test your connection:
Enable your webhook – Make sure it's ready to receive requests
Disable callbacks temporarily – Turn off any modules that send data back during testing
Click "Test Connection" – We'll send a sample POST request
Check the results – Green checkmark means success
Error handling best practices
💡 Keep your automation running
Test connections use sample data that may cause processing failures. Configure error handling in your automation to:
• Catch errors without deactivating your agent
• Log issues for debugging while staying active
• Continue processing new requests even after failures
This prevents your automation from being disabled during testing or when real orders encounter issues.
⚠️ Important testing tip
During connection testing, disable any callback or response modules in your automation. These can interfere with the test by sending data back to us prematurely. Save the full workflow with callbacks for production use.
Common test failures and fixes
Authentication errors
401/403 errors – Add correct Authorization: Bearer or x-api-key header
Wrong token format – Check if your platform expects a specific header format
Expired tokens – Refresh OAuth tokens or generate new API keys
URL and routing errors
404 errors – Double-check webhook URL path and spelling
405 errors – Ensure endpoint accepts POST requests with JSON
3xx redirects – Use the final HTTPS URL, not one that redirects
Content type errors
415/422 errors – Configure endpoint to accept application/json
Parsing errors – Make sure your webhook can parse JSON payloads
Network errors
Timeouts – Check if your automation platform is accessible
DNS errors – Verify domain name resolves correctly
SSL errors – Ensure valid HTTPS certificate
Platform-specific guidance
Make.com
URL format: https://hook.make.com/your-hook-id
Headers: Add custom header in HTTP module settings
Testing: Enable webhook, disable callback modules during test
Use strong tokens – Generate secure, unique authentication tokens
Rotate regularly – Change tokens periodically for better security
Monitor access – Watch for unusual webhook activity
Validate payloads – Check that incoming requests match expected format
Log requests – Keep records for debugging and security monitoring
Testing workflow
Set up webhook – Configure your automation to receive JSON POST requests
Add authentication – Ensure your webhook validates the auth headers
Test locally first – Use tools like ngrok or Postman to verify
Configure in SellerShorts – Enter URL, headers, and callback settings
Run connection test – Verify everything works together
Fix any issues – Use error messages to troubleshoot problems
What's next?
After successfully connecting your automation, you'll move to the Test step where you can run a complete test order to verify your AI Tool works end-to-end.
