Webhook Payload Structure - Website Visitor Identified

# Webhook Payload Structure When HappierLeads identifies a website visitor, we send a POST request to your configured webhook URL with detailed information about the visitor and their company. ## Overview The webhook is triggered when: - A visitor is identified on your website - We have successfully enriched the company data - The visitor's company domain is valid The webhook request is sent as a **JSON POST** request with a **10-second timeout** and includes the following headers: ``` Content-Type: application/json ``` ## Complete Payload Structure ```json { "leadId": "507f1f77bcf86cd799439011", "clientId": "app_1234567890", "websiteId": "607f1f77bcf86cd799439022", "workspaceName": "My Workspace", "ip": "192.168.1.1", "isFirstVisit": true, "isWebhookSentForFirstTime": true, "pageVisits": [ { "url": "https://example.com/pricing", "title": "Pricing - Example", "timestamp": "2024-01-15T10:30:00.000Z" }, { "url": "https://example.com/features", "title": "Features - Example", "timestamp": "2024-01-15T10:32:15.000Z" } ], "company": { "domain": "acme.com", "name": "acme corporation", "yearFounded": 2015, "companyType": "private", "sector": "Technology", "industry": "Software", "postalCode": "94105", "state": "California", "country": "United States", "countryCode": "US", "estimatedAnnualRevenue": "$10M-$50M", "employeesRange": "50-200", "alexaRank": 125000, "linkedinPage": "https://linkedin.com/company/acme" }, "summary": "Technology company specializing in enterprise software solutions", "scores": [ { "type": "engagement", "value": 85, "timestamp": "2024-01-15T10:30:00.000Z" } ], "contact": { "name": "John Doe", "title": "Senior Product Manager", "email": "john.doe@acme.com", "personalEmail": "john@gmail.com", "phone": "+1-555-0123", "linkedinUrl": "https://linkedin.com/in/johndoe", "workspaceName": "My Workspace", "geo": { "city": "San Francisco", "state": "California", "country": "United States", "countryCode": "US", "fullAddress": "San Francisco, California, United States" }, "additionalContacts": [ { "name": "Jane Smith", "title": "VP of Sales", "email": "jane.smith@acme.com" } ], "listContacts": [] } } ``` ## Field Descriptions ### Root Level Fields | Field | Type | Description | |-------|------|-------------| | `leadId` | string | Unique identifier for this lead in HappierLeads | | `clientId` | string | Your application/client identifier | | `websiteId` | string | The ID of the website where the visitor was tracked | | `workspaceName` | string | Name of the workspace this lead belongs to | | `ip` | string | IP address of the visitor | | `isFirstVisit` | boolean | `true` if this is the visitor's first session | | `isWebhookSentForFirstTime` | boolean | `true` if this is the first time a webhook has been sent | | `pageVisits` | array | Array of page visit objects with URL, title, and timestamp | | `company` | object | Enriched company data (see Company Object below) | | `summary` | string | AI-generated summary of the company | | `scores` | array | Array of scoring objects (engagement, quality, etc.) | | `contact` | object | Contact person information (if identified) | ### Company Object | Field | Type | Description | |-------|------|-------------| | `domain` | string | Company domain (e.g., "acme.com") | | `name` | string | Company name (lowercase) | | `yearFounded` | number | Year the company was founded | | `companyType` | string | Type of company (e.g., "private", "public") | | `sector` | string | Business sector | | `industry` | string | Specific industry | | `postalCode` | string | Company postal/zip code | | `state` | string | Company state/region | | `country` | string | Company country | | `countryCode` | string | Two-letter country code (e.g., "US") | | `estimatedAnnualRevenue` | string | Revenue range (e.g., "$10M-$50M") | | `employeesRange` | string | Employee count range (e.g., "50-200") | | `alexaRank` | number | Alexa global ranking | | `linkedinPage` | string | LinkedIn company page URL | ### Contact Object (Optional) The contact object is only included when we successfully identify the specific visitor. | Field | Type | Description | |-------|------|-------------| | `name` | string | Contact's full name | | `title` | string | Job title | | `email` | string | Work email address | | `personalEmail` | string | Personal email (if available) | | `phone` | string | Phone number | | `linkedinUrl` | string | LinkedIn profile URL | | `workspaceName` | string | Workspace name | | `geo` | object | Visitor's geographic location | | `additionalContacts` | array | Other contacts from the same company | | `listContacts` | array | Contacts from uploaded lists | ### Geo Object (within Contact) | Field | Type | Description | |-------|------|-------------| | `city` | string | City name | | `state` | string | State/region | | `country` | string | Country name | | `countryCode` | string | Two-letter country code | | `fullAddress` | string | Formatted address string | ## Important Notes 1. **Null Values**: Any field can be null if the data is not available 2. **Timeout**: Webhooks have a 10-second timeout - ensure your endpoint responds quickly 3. **First Visit**: Use `isFirstVisit` to identify new visitors vs. returning visitors 4. **Contact Data**: The `contact` object is optional and only included when visitor identity is determined 5. **Page Visits**: Track visitor behavior through the `pageVisits` array 6. **Visitor Location**: Geographic data in `contact.geo` represents the visitor's location, while `company` geo data represents the company headquarters ## Testing Your Webhook You can test your webhook endpoint using this example cURL command: ```bash curl -X POST https://your-webhook-url.com/webhook \ -H "Content-Type: application/json" \ -d '{ "leadId": "507f1f77bcf86cd799439011", "ip": "192.168.1.1", "isFirstVisit": true, "company": { "domain": "test-company.com", "name": "test company" } }' ``` ## Error Handling If your webhook endpoint: - Returns an error status code (4xx, 5xx) - Times out after 10 seconds - Is unreachable The webhook will fail, and the error will be logged in our system. We recommend implementing: - Proper error logging on your endpoint - Quick response times (< 5 seconds) - Retry logic on your end if needed - Queue-based processing for heavy operations ## Response Your webhook endpoint should return a **200 OK** status code to indicate successful receipt of the data. The response body is optional and not processed by HappierLeads.