Webhook Integration Guide

This document describes both outbound webhooks (sent by LeadSource to your systems) and inbound webhooks (received by LeadSource from your systems).

---

Outbound Webhooks

Outbound webhooks notify your systems when events occur in LeadSource. Configure webhook endpoints via the dashboard.

Events

Event	Description
LEAD_WON	Fired when a lead is matched to one of your campaigns
TEST	Sent when testing a webhook endpoint

LEAD_WON Payload

{
  "event": "LEAD_WON",
  "lead": {
    "hashid": "abc123",
    "email": "[email protected]",
    "phone": "5551234567",
    "firstName": "John",
    "lastName": "Doe",
    "address": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94102",
    "service": "HVAC Repair",
    "priceInCents": 5000,
    "priceInDollars": 50,
    "data": { "...": "miscellaneous data provided with the lead" }
  },
  "campaign": {
    "hashid": "xyz789",
    "name": "SF Bay Area HVAC"
  },
  "account": {
    "hashid": "123abc"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Field Reference

lead object

Field	Type	Description
hashid	string	Unique lead identifier
email	string	Lead's email address
phone	string	Lead's phone (normalized, digits only)
firstName	string	First name
lastName	string	Last name
address	string	Street address
city	string	City
state	string	State (2-letter code)
zipCode	string	ZIP code
service	string	Specific service requested
priceInCents	number	Price paid for this lead in cents
priceInDollars	number	Price paid for this lead in dollars
data	object	Miscellaneous data provided with the lead

campaign object

Field	Type	Description
hashid	string	Campaign identifier
name	string	Campaign name

account object

Field	Type	Description
hashid	string	Account identifier (the LeadSource account that owns the receiving campaign)

TEST Payload

Test payloads have the same structure as LEAD_WON but with event: "TEST" and sample data. Use this to verify your endpoint is receiving webhooks correctly.

Retry Policy

Failed webhook deliveries are retried with exponential backoff. Webhooks are considered failed if:

• HTTP status code is not 2xx
• Connection timeout (30 seconds)
• DNS resolution failure

---

Inbound Webhooks

Inbound webhooks allow your systems to send data back to LeadSource (e.g., conversion tracking).

Endpoint

POST /webhooks/:accountHashid/:token

• accountHashid: Your account identifier
• token: Secret token for authentication (generated when creating an inbound webhook endpoint)

Authentication

Requests are authenticated via the URL token. No additional headers required.

Events

lead_update (default)

Report lead status changes and deal value back to LeadSource.

Request:

{
  "event": "lead_update",
  "externalLeadId": "crm_id_123",
  "email": "[email protected]",
  "phone": "5551234567",
  "status": "CLOSED_WON",
  "leadValue": 150.00
}

Field	Type	Required	Description
event	string	No	Event type. Defaults to "lead_update" if omitted. "lead_update" is currently the only supported value
externalLeadId	string	One of externalLeadId/email/phone	Your system's identifier for the lead (e.g. CRM contact ID). Highest-priority matcher
email	string	One of externalLeadId/email/phone	Lead's email for matching
phone	string	One of externalLeadId/email/phone	Lead's phone for matching
status	string	No	Lead status (see values below)
leadValue	number	No	Deal value in dollars
leadValueCents	number	No	Deal value in cents. If both leadValue and leadValueCents are provided, leadValueCents is used

Valid status values

Status	Description
OPEN	Lead created, no activity yet
CONTACTED	Lead has been contacted
APPOINTMENT_BOOKED	Appointment scheduled with lead
QUOTED	Quote or proposal sent
CLOSED_WON	Deal closed successfully
CLOSED_LOST	Deal lost
UNKNOWN	Status unknown (default if value is missing or unrecognized)

Status matching is case-insensitive, and common variants are accepted (e.g. closed-won, proposal_sent, booked). Unrecognized values are stored as UNKNOWN.

Response:

{
  "received": true,
  "matched": true
}

Field	Type	Description
received	boolean	Always true for valid requests
matched	boolean	Whether a matching lead was found
error	string	Error message if request was invalid

Lead Matching

Leads are matched in priority order: externalLeadId → email → phone. Only leads belonging to campaigns owned by the authenticated account are considered. The most recently created matching lead is updated.

---

Dashboard Setup

Inbound Webhooks

1. Navigate to Webhooks > Inbound tab
2. Click Create Webhook Endpoint (if none exists)
3. Copy the generated webhook URL
4. Use this URL in external systems to POST conversion data
5. Options: Regenerate Token (invalidates old URL) or Delete Endpoint

Note: Only one inbound endpoint per account.

Outbound Webhooks

Create:

1. Navigate to Webhooks > Outbound tab
2. Click Create Webhook
3. Fill in:
   • Name - identifier for the webhook
   • URL - destination endpoint (e.g., Zapier hook)
   • Event - trigger event (currently: New Lead)
   • Campaign - optional filter (all or specific campaign)
4. Use Test button to verify URL before saving
5. Click Create Webhook

Edit/Delete:

1. Click webhook name in list to view details
2. Use Test, Edit, or Delete buttons in header

Dispatch History: View past webhook deliveries with payload details on the webhook detail page.