Skip to content

API.md

Latest commit

 

History

History
172 lines (138 loc) · 4.98 KB

API.md

File metadata and controls

172 lines (138 loc) · 4.98 KB
Raw

🔌 LeadIQ-AI — Webhook API Specification

Endpoint Version: v2
Base URL: http://localhost:5678/webhook (or production n8n domain)
Protocol: HTTPS / HTTP POST
Authentication: X-Webhook-Secret; required in production and configurable elsewhere via N8N_WEBHOOK_AUTH_REQUIRED

1. Webhook Ingestion Endpoint

POST /webhook/leadiq

Ingests lead information, triggers normalized schema parsing, acquires Supabase concurrency reservation, executes Gemini AI qualification (if non-duplicate), and routes alerts.

Request Headers

Header Type Required Description
Content-Type String Yes Must be application/json
X-Webhook-Secret String Production Must match N8N_WEBHOOK_SECRET when authentication is required

Request Body Schema

Field Type Required Description Example
name String Yes Full name of the lead contact "Sarah Jenkins"
email String Yes Lead email address (normalized automatically) "s.jenkins@enterprise-tech.com"
company String Yes Company or organization name "Enterprise Tech Solutions"
message String Yes Inquiry or demo request message text "We have an urgent budget..."
job_title String No Lead's job title or role "VP of Engineering"
phone String No Contact phone number "+1-555-019-2834"
country String No Country of operation "United States"
source String No Lead acquisition channel / form source "Web Form"
utm_source String No UTM source tracking parameter "google"
utm_medium String No UTM medium tracking parameter "cpc"
utm_campaign String No UTM campaign tracking parameter "ai-tools-q3"

Sample Request Payload

{
  "name": "Sarah Jenkins",
  "email": "s.jenkins@enterprise-tech.com",
  "company": "Enterprise Tech Solutions",
  "job_title": "VP of Engineering",
  "message": "We have an urgent budget of $50,000 to deploy AI lead automation across our sales team of 40 reps by next month.",
  "phone": "+1-555-019-2834",
  "country": "United States",
  "source": "Web Form",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "ai-tools-q3"
}

2. Response Codes & Payloads

200 OK — Successful Qualification (New Lead)

Returned when a lead is successfully processed and qualified.

{
  "status": "success",
  "lead_id": "LEAD-20260718-A3F9C1",
  "email": "s.jenkins@enterprise-tech.com",
  "score": 92,
  "tier": "HOT",
  "reasoning": "High commercial intent with specific $50k budget, 40-rep team size, and immediate deployment timeline.",
  "routing": {
    "google_sheets": "appended",
    "slack_alert": "sent",
    "gmail_acknowledgement": "skipped"
  },
  "duplicate_status": "OWNER",
  "metadata": {
    "pipeline_version": "v2",
    "execution_duration_ms": 1667,
    "environment": "development",
    "duplicate_detected": false,
    "processing_status": "success_processed"
  }
}

200 OK — Duplicate Handled (10-Minute Window)

Returned when an inbound email was already processed within the 10-minute duplicate window. Bypasses Gemini API, Google Sheets append, and Slack/Gmail alerts. Reuses original qualification data.

{
  "status": "duplicate_handled",
  "lead_id": "LEAD-20260718-A3F9C1",
  "email": "s.jenkins@enterprise-tech.com",
  "score": 92,
  "tier": "HOT",
  "duplicate_status": "DUPLICATE_COMPLETED",
  "message": "Lead was qualified within the 10-minute duplicate window. Reused cached AI result.",
  "metadata": {
    "pipeline_version": "v2",
    "execution_duration_ms": 666,
    "environment": "development",
    "duplicate_detected": true,
    "processing_status": "duplicate_bypass"
  }
}

400 Bad Request — Schema Validation Error

Returned when required payload parameters are missing or invalid.

{
  "status": "error",
  "code": 400,
  "errors": [
    "'name' is required and must be a non-empty string.",
    "'email' value \"badmail\" is not a valid email address."
  ]
}

3. Health Check Endpoint

GET /webhook/leadiq-health

Exposes pipeline status, version, and server environment metadata.

Response (HTTP 200 when ready; HTTP 503 when required configuration is missing)

{
  "status": "healthy",
  "version": "v2",
  "ready": true,
  "environment": "development",
  "timestamp": "2026-07-18T10:17:35.001Z"
}

4. Example cURL Commands

Submit a Lead

curl -X POST "http://localhost:5678/webhook/leadiq" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: ${N8N_WEBHOOK_SECRET}" \
  -d '{
    "name": "Sarah Jenkins",
    "email": "s.jenkins@enterprise-tech.com",
    "company": "Enterprise Tech Solutions",
    "message": "Testing webhook integration.",
    "phone": "+1-555-019-2834",
    "country": "United States",
    "source": "API Test"
  }'

Check Pipeline Health

curl "http://localhost:5678/webhook/leadiq-health"