A webhook handler that captures sponsored lead ad submissions from LinkedIn's Lead Sync API and forwards them to PostHog for analytics and tracking.

This integration automatically captures lead data from LinkedIn sponsored lead ads and sends structured events to PostHog, enabling comprehensive lead tracking, analysis, and funnel optimization.

• Automatic Lead Capture: Receives webhooks from LinkedIn Lead Sync API
• Flexible Data Parsing: Handles multiple LinkedIn webhook formats
• Rich Event Data: Captures comprehensive lead information including contact details, campaign metadata, and custom fields
• PostHog Integration: Sends structured events to PostHog for analytics
• Error Handling: Robust error handling with detailed logging
• Cross-Platform: Works with Node.js, Deno, and other JavaScript runtimes

• captureLinkedInLeadsWebhook.ts - Main webhook handler for LinkedIn Lead Sync API
• capturePostHogEvent.ts - PostHog event capture utility
• README.md - This documentation file

Set the following environment variable:

phProjectAPIKey=your_posthog_project_api_key_here

1. Go to your PostHog project settings
2. Navigate to "API Keys" section
3. Copy your Project API Key
4. Set it as the phProjectAPIKey environment variable

1. Set up your LinkedIn Lead Sync API webhook endpoint
2. Configure your LinkedIn sponsored lead ads to send webhooks to your endpoint
3. Ensure your webhook URL points to the endpoint running this handler

Deploy the captureLinkedInLeadsWebhook function as a webhook endpoint:

import { captureLinkedInLeadsWebhook } from "./captureLinkedInLeadsWebhook.ts";

// Example usage in a web framework
app.post("/webhook/linkedin-leads", captureLinkedInLeadsWebhook);

The integration sends the following events to PostHog:

• linkedin_lead_submitted - New lead submission
• linkedin_lead_updated - Lead data updated
• linkedin_lead_deleted - Lead deleted

{
  // Contact Information
  email: string,
  first_name: string,
  last_name: string,
  full_name: string,
  phone: string,
  
  // Company Information
  company: string,
  job_title: string,
  industry: string,
  company_size: string,
  
  // Location Data
  country: string,
  state: string,
  city: string,
  zip_code: string,
  
  // LinkedIn Campaign Data
  campaign_id: string,
  ad_id: string,
  form_id: string,
  lead_id: string,
  lead_score: number,
  
  // Metadata
  source: "linkedin_ads",
  event_type: string,
  created_at: string,
  submitted_at: string,
  custom_fields: object
}

The integration handles multiple LinkedIn webhook formats:

{
  "email": "lead@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "company": "Acme Corp",
  "campaignId": "12345",
  "formId": "67890"
}

{
  "event": "lead.created",
  "data": {
    "email": "lead@example.com",
    "firstName": "John",
    "lastName": "Doe"
  }
}

{
  "lead_email": "lead@example.com",
  "First_Name": "John",
  "Last_Name": "Doe",
  "Company": "Acme Corp"
}

{
  "ok": true,
  "event": "linkedin_lead_submitted",
  "user": "lead@example.com",
  "lead_id": "12345",
  "source": "linkedin_ads"
}

{
  "error": "LinkedIn Leads processing failed",
  "details": "Missing required payload data - email not found"
}

The integration includes comprehensive error handling:

• Missing Email: Returns 400 if no email is found in the payload
• Missing API Key: Returns 500 if PostHog API key is not configured
• PostHog Errors: Logs and handles PostHog API errors
• JSON Parsing: Handles malformed JSON payloads
• Detailed Logging: Comprehensive console logging for debugging

The integration provides detailed logging:

=== LinkedIn Leads Webhook received ===
Raw payload: {...}
Event type: lead.created
Lead data: {...}
API key exists: true
Mapped event name: linkedin_lead_submitted
About to call PostHog with: {...}
PostHog result: Event captured successfully
=== LinkedIn Leads webhook processing complete ===

You can test the integration with a sample payload:

{
  "event": "lead.created",
  "data": {
    "email": "test@example.com",
    "firstName": "Test",
    "lastName": "User",
    "company": "Test Company",
    "campaignId": "test-campaign-123",
    "formId": "test-form-456"
  }
}

After sending a test webhook, verify in PostHog:

1. Go to your PostHog project
2. Navigate to "Events" in the sidebar
3. Look for events with name linkedin_lead_submitted
4. Verify the event properties contain the expected data

• API Key Protection: Keep your PostHog API key secure and never commit it to version control
• Webhook Validation: Consider implementing webhook signature validation for production use
• Rate Limiting: Implement rate limiting if needed for your use case
• HTTPS: Always use HTTPS for webhook endpoints in production

1. "Missing PostHog API key"

   • Ensure phProjectAPIKey environment variable is set
   • Verify the API key is valid in PostHog

2. "Invalid payload - missing email"

   • Check that your LinkedIn webhook is sending email data
   • Verify the webhook payload structure matches expected format

3. PostHog events not appearing

   • Check PostHog API key permissions
   • Verify network connectivity to PostHog
   • Check PostHog project settings

Enable detailed logging by checking the console output for:

• Raw webhook payload
• Event type detection
• Property extraction
• PostHog API responses

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

This project is open source. Please check the license file for details.

For issues and questions:

1. Check the troubleshooting section above
2. Review PostHog documentation for API issues
3. Check LinkedIn Lead Sync API documentation for webhook format questions
4. Create an issue in the repository if problems persist