Connect
💡 Custom Payload Template
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 Short, we need to send their inputs to your automation and receive the results back. This step establishes the technical connection between SellerShorts and your AI automation platform.
Webhook payload with job_token (Amazon Ads)
If your AI Short requires Amazon Ads (configured in the Inputs step), your webhook payload includes an additional job_token field:
{
"short_id": "abc123",
"order_id": "550e8400-e29b-41d4-a716-446655440000",
"inputs": {
"date_range": { "from": "2024-01-01", "to": "2024-01-31" }
},
"callback_url": "https://api.sellershorts.com/api/orders/callback",
"ts": 1736032405,
"job_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
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.
Learn more about using job_token with Amazon Ads →
Required configuration
Auth directions (quick reference)
- 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/abc123xyzhttps://api.n8n.cloud/webhook/uuidhttps://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
n8n
- URL format:
https://your-instance.n8n.cloud/webhook/your-path - Headers: Configure in Webhook node authentication tab
- Testing: Set webhook to "Test URL" mode initially
Relevance AI
- URL format: Custom endpoint in your workspace
- Headers: Use
Authorization: Bearer workspace-token - Testing: Test endpoint separately before connecting
Botpress
- URL format:
https://webhook.botpress.cloud/your-bot-id - Headers: Configure in bot webhook integration settings
- Testing: Enable webhook integration, check bot logs
Security best practices
- 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 Short works end-to-end.