Skip to main content
POST
/
webhooks
/
ai-recommendation-store
curl -X POST https://searchcompany-main.up.railway.app/webhooks/ai-recommendation-store \
  -H "Content-Type: application/json" \
  -d '{
    "page_url": "https://alphax-inc.searchcompany.dev/",
    "page_type": "ai_site",
    "page_title": "AlphaX Technologies - AI Profile",
    "user_agent": "Mozilla/5.0 (compatible; GPTBot/1.0; +https://openai.com/gptbot)",
    "ip_address": "52.167.144.0",
    "referrer": "https://chat.openai.com/",
    "screen_width": 1920,
    "screen_height": 1080,
    "language": "en-US",
    "timezone": "America/New_York"
  }'

{
  "status": "success",
  "platform_id": "chatgpt",
  "platform_name": "ChatGPT",
  "message": "AI recommendation from ChatGPT recorded"
}
Public webhook endpoint for storing AI recommendations from tracking scripts embedded in AI-optimized sites. 1 AI recommendation = 1 AI bot visiting your site When GPTBot, ClaudeBot, or any other AI crawler visits your AI site, that counts as one AI recommendation. No authentication required - this is a public webhook similar to the Stripe webhook.

​
How It Works

  1. AI-optimized sites include a dynamic tracking script loaded from /tracking.js
  2. The script detects AI bots via user-agent patterns
  3. When an AI bot is detected, the script sends the visit to this endpoint
  4. We record it as an AI recommendation in the ai_recommendations table

​
Supported AI Platforms

PlatformDetection Patterns
ChatGPTgptbot, chatgpt-user, oai-searchbot
Claudeclaudebot, claude-web, anthropic
Geminigoogle-extended, gemini
Perplexityperplexitybot
Copilotbingbot, bingpreview, copilot
DeepSeekdeepseekbot
Grokxai-bot, grok
Google AIgooglebot, googleother

​
Request Body

​
page_url
string
required
Full URL of the page visited (entity is looked up from the domain automatically)
​
page_type
string
default:"ai_site"
Type of page: ai_site or boosted_page
​
page_title
string
Title of the page
​
user_agent
string
required
User-Agent header from the request
​
ip_address
string
IP address of the visitor
​
referrer
string
Referrer URL if available
​
screen_width
integer
Screen width in pixels
​
screen_height
integer
Screen height in pixels
​
language
string
Browser language (e.g., en-US)
​
timezone
string
Browser timezone (e.g., America/New_York)

​
What Gets Stored

The backend automatically adds:
  • created_at: Timestamp when the recommendation was recorded (UTC)
  • entity_id: Looked up from the page_url domain
  • ai_site_id: The AI site associated with the entity
  • platform_id: Detected from user_agent (or unknown if not recognized)
  • platform_name: Human-readable platform name

​
Response

​
status
string
"success", "ignored", or "error"
​
platform_id
string
ID of the detected AI platform (e.g., chatgpt, claude)
​
platform_name
string
Display name of the AI platform (e.g., ChatGPT, Claude)
​
message
string
Human-readable status message
curl -X POST https://searchcompany-main.up.railway.app/webhooks/ai-recommendation-store \
  -H "Content-Type: application/json" \
  -d '{
    "page_url": "https://alphax-inc.searchcompany.dev/",
    "page_type": "ai_site",
    "page_title": "AlphaX Technologies - AI Profile",
    "user_agent": "Mozilla/5.0 (compatible; GPTBot/1.0; +https://openai.com/gptbot)",
    "ip_address": "52.167.144.0",
    "referrer": "https://chat.openai.com/",
    "screen_width": 1920,
    "screen_height": 1080,
    "language": "en-US",
    "timezone": "America/New_York"
  }'

{
  "status": "success",
  "platform_id": "chatgpt",
  "platform_name": "ChatGPT",
  "message": "AI recommendation from ChatGPT recorded"
}