Webhooks

Integrate Relixir with your systems using webhooks

Overview

Relixir provides webhook integrations for visitor identification and event tracking. The primary webhook integration is for Visitor ID data, which processes visitor identification events with advanced attribution, AI search detection, and blog tracking.

---

Warmly Webhook Integration

The Warmly webhook integration powers Relixir’s Visitor ID feature, providing:

Visitor Identification

Process visitor identification events with company and contact enrichment

AI Search Detection

Automatically detect visits from ChatGPT, Perplexity, Gemini, Claude, and more

Traffic Attribution

Classify traffic sources (paid, organic, social, AI search, etc.)

Blog Tracking

Match page views to Relixir blog deployments for attribution

---

Webhook Endpoint

POST /webhooks/warmly/{organization_id}

Headers

Header	Value
Content-Type	application/json

Path Parameters

Parameter	Description
organization_id	Your Relixir organization UUID

---

Request Payload

The webhook accepts the standard Warmly webhook payload format. Key fields include:

{
  "event_type": "contact_visit",
  "session": {
    "session_id": "uuid",
    "pages": [
      {
        "url": "https://example.com/blog/post-slug",
        "referrer": "https://chat.openai.com/",
        "timestamp": "2026-02-03T10:00:00Z"
      }
    ]
  },
  "company": {
    "name": "Acme Corp",
    "domain": "acme.com",
    "industry": "Technology"
  },
  "contact": {
    "email": "[e-mail]",
    "name": "John Doe",
    "linkedin_url": "https://linkedin.com/in/johndoe"
  }
}

---

Response Format

Success Response

{
  "status": "success",
  "raw_webhook_id": "uuid",
  "company_id": "uuid",
  "contact_id": "uuid",
  "visit_id": "uuid",
  "page_view_count": 4
}

Error Response

{
  "status": "error",
  "error": "Error message describing the issue"
}

---

AI Search Engine Detection

The webhook automatically detects visits from AI search engines:

AI Engine	Detection Method
ChatGPT	UTM source parameter, referrer URL
Perplexity AI	Referrer URL
Google Gemini/Bard	Referrer URL
Claude AI	Referrer URL
Phind	Referrer URL
You.com	Referrer URL
Bing Chat	Referrer URL
DeepSeek	Referrer URL

---

Traffic Classification

All traffic is classified into categories:

Category	Description
ai_search	AI search engines (ChatGPT, Perplexity, etc.)
paid_search	Paid advertising (CPC, PPC campaigns)
search	Organic search (Google, Bing, etc.)
social	Social media (LinkedIn, Twitter, etc.)
email	Email campaigns
referral	Other website referrals
direct	Direct traffic (no referrer)

---

Blog Attribution

The webhook matches page URLs to deployed Relixir blogs:

• Handles slug prefixes (e.g., /post/, /blog/)
• Links visits to tracked actions
• Tracks which sessions hit Relixir-generated content

This enables attribution of:

• Which blogs drive traffic
• Which content sources AI visitors engage with
• Full visitor journey through your content

---

Database Tables

The webhook writes to 5 tables:

Table	Purpose
raw_webhook_response	Complete webhook payload for auditing
dim_identified_visitor_company	Company enrichment data
dim_identified_visitor_contact	Contact information
fact_identified_visit	Visit-level facts with attribution
fact_page_view	Page-level analytics

---

Key Log Messages

When monitoring webhook processing, look for these log messages:

INFO - Processing webhook for organization {id}
INFO - Detected AI search engine: {name}
INFO - Session hit Relixir blog! Deployment: {id}
INFO - Created new company: {id} for domain {domain}

---

Success Metrics

Monitor these metrics for webhook health:

Metric	Target
Processing success rate	Greater than 99%
AI search detection rate	Track improvement over time
Blog attribution accuracy	Validate against known traffic
Processing latency	Less than 3 seconds at p95

---

Troubleshooting

Webhooks are failing

• Ensure the organization exists in the Relixir database
• Verify the organization ID in the URL is correct
• Check logs for detailed error messages

Blog matching not working

• Verify BlogSettings.blogSlugPrefix is configured correctly
• Check that deployment slugs match URL paths
• Confirm blogs are deployed (not just drafted)

AI search not being detected

• Check the referrer URL format in the payload
• Verify UTM parameters are present (for ChatGPT)
• Some AI engines may need to be added to detection logic

Company/contact not enriched

• Enrichment requires sufficient information in the payload
• Some visitors may not have associated company data
• Check that Warmly is providing complete data

---

Integration Setup

To configure the Warmly webhook integration:

1. Get your Organization ID from Relixir Settings
2. Configure Warmly to send webhooks to:
   https://api.relixir.ai/webhooks/warmly/{your-organization-id}
   
3. Test the integration by visiting your site and checking the Contacts page

Need help setting up webhooks? Contact [e-mail].