Placeholders & Keys

Understanding the data we send to your webhook and how to use placeholders helps you build reliable automations that work consistently with buyer inputs.

Webhook payload structure

When a buyer runs your AI Short, we POST this JSON to your webhook:

{
  "short_id": "abc123",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "inputs": {
    "website_url": "https://example.com",
    "keywords": "selling, seo, optimization",
    "include_technical": true
  },
  "callback_url": "https://api.example.com/callback",
  "ts": 1736032405
}

Payload fields explained

• short_id – Your AI Short's unique identifier
• order_id – Unique UUID for this specific order (required for callbacks)
• inputs – Object containing all buyer-provided data using your defined keys
• callback_url – Where to POST results when processing completes
• ts – Unix timestamp when the order was created

Input key mapping

The keys you define in the Inputs step become properties in the inputs object. This direct mapping ensures your automation receives data in the exact format you expect.

Key validation rules

• Format: Must match ^[a-z][a-zA-Z0-9_]{1,39}$
• Start: Begin with lowercase letter
• Characters: Only letters, numbers, underscores
• Length: Maximum 40 characters total
• Uniqueness: Each key must be unique within your AI Short

Good key examples

• website_url – Clear, descriptive
• target_keywords – Multi-word with underscore
• max_results – Number input key
• include_images – Boolean input key
• start_date – Date input key

Bad key examples

• URL – Doesn't start with lowercase
• website-url – Contains hyphen (not allowed)
• website url – Contains space (not allowed)
• a – Too short, not descriptive

Using placeholders

Order ID placeholder

For optional polling endpoints, use {order_id} as a placeholder:

• Example URL: https://api.yourtool.com/status/{order_id}
• Becomes: https://api.yourtool.com/status/550e8400-e29b-41d4-a716-446655440000
• Purpose: We substitute the actual order UUID when polling
• Use case: When your automation can't use callbacks

Working with input data

Accessing inputs in your automation

Different platforms handle JSON data differently:

Make.com

• Access: {{1.inputs.website_url}}
• Mapping: Use the exact key names from your configuration
• Arrays: Multi-select inputs become arrays automatically

n8n

• Access: {{$json.inputs.website_url}}
• Validation: Check if keys exist before using
• Type checking: Validate data types in your workflow

Relevance AI

• Access: inputs.website_url in workflow steps
• Variables: Use input keys directly in agent prompts
• Validation: Configure input validation in workflow settings

Botpress

• Access: {{event.payload.inputs.website_url}}
• Mapping: Reference webhook data in conversation flow
• Processing: Use inputs in bot logic and responses

Input data types

Different input types produce different data formats:

• text, textarea, url: String values
• number: Numeric values (integer or float)
• boolean: true or false
• date: ISO date string (e.g., "2024-01-15")
• date_range: Object with start and end properties
• select: Single string value from your options
• multiselect: Array of strings
• tags: Array of strings (split from comma-separated input)
• files: Array of file objects with metadata and content

File input structure

File inputs produce objects with metadata and content:

{
  "inputs": {
    "upload_document": [
      {
        "filename": "report.pdf",
        "mime_type": "application/pdf",
        "size_bytes": 524288,
        "file_base64": "base64-encoded-content..."
      }
    ]
  }
}

Best practices

• Use descriptive keys – product_title is better than title
• Be consistent – Use similar patterns across all your AI Shorts
• Validate inputs – Check data exists and is the expected type
• Handle missing data – Provide defaults for optional inputs
• Document your keys – Keep a reference of what each key represents