What are "Web Hook" lead notifications?

Every Lead Manager account has the option to communicate lead notifications with a web server whenever a new lead is received. These "Web Hooks" can be used to update external customer relationship management software (CRM), trigger custom notifications, or update an external database.

The payload

When a new lead is matched to your account, we'll POST to your URL with a payload of XML-formatted data about the lead and their request. Here is a sample payload: 
<?xml version="1.0" encoding="utf-8"?>
<Lead>
  <FirstName>James</FirstName>
  <LastName>Evans</LastName>
  <Address>3462 Rivendell Drive</Address>
  <City>Youngstown</City>
  <State>OH</State>
  <ZipCode>44509</ZipCode>
  <PhoneNumber>3305556274</PhoneNumber>
  <DirectLeadPhoneNumber>3305556274</DirectLeadPhoneNumber>
  <EmailAddress>james.evans@testdomain.org</EmailAddress>
  <LeadId>25</LeadId>
  <ServiceId>3000</ServiceId>
  <ServiceName>Install or Replace Asphalt Roof</ServiceName>
  <ServiceAreaName>Coopers Patio Inspection - First Area</ServiceAreaName>
  <Service>Roofing</Service>
  <TimeFrame>Anytime</TimeFrame>
  <Notes>This is a test webhook notification.</Notes>
  <OriginalPrice>50.0</OriginalPrice>
  <DiscountedPrice>45.0</DiscountedPrice>
  <TrustedForm>https://cert.trustedform.com/4eace04f</TrustedForm>
  <CustomerType>commercial</CustomerType>
  <IpAddress>10.0.0.1</IpAddress>
  <AdditionalDetails>
	<Detail question="Did you request a test webhook notification?">Yes</Detail>
  </AdditionalDetails>
</Lead>

This is sent as a POST with the Content-Type set to " application/xml".
Note: 
  • The PhoneNumber field will contain the Speed-To-Call phone number if you are signed up to receive the Speed-To-Call Discount.  The DirectLeadPhoneNumber field will always contain the lead's actual phone number.  
  • The DiscountedPrice will only reflect promotions on your account, not our Speed-To-Call Discount because that discount can only be applied after the webhook is sent.

Testing

When you set up your webhook notification, you can send yourself a test from LeadManager.  If you do not receive anything, there is likely a problem with how your webhook endpoint is set up.  Postman is a very useful tool for troubleshooting these sorts of problems.  It can be obtained here for free:  https://www.getpostman.com/
All you need to do to send yourself a test in Postman after downloading it is create a new POST request, put your webhook url in the url field, and paste the above sample in the body of the request.  Ensure that it is being sent as " application/xml", and click "Send" when you want to receive the request:

Customizing the WebHook Payload

The webhook payload can be customized if you prefer not to accept the default xml payload.
To customize, choose your preferred content type and add your custom payload template. The lead fields will be inserted where you specify them using the {{fieldName}} syntax. Here is an example application/json template: 
{
	"firstName": "{{FirstName}}",
	"lastName": "{{LastName}}",
	"address": "{{Address}}",
	"city": "{{City}}",
	"state": "{{State}}",
	"zip": "{{ZipCode}}",
	"phone": "{{PhoneNumber}}",
	"directPhone": "{{DirectLeadPhoneNumber}}",
	"email": "{{EmailAddress}}",
	"serviceID": {{ServiceId}},
	"craftjackLeadID": {{LeadId}},
	"created": "{{ReceivedOn}}",
	"serviceName": "{{ServiceName}}",
	"serviceAreaName": "{{ServiceAreaName}}",
	"serviceCategory": "{{Service}}",
	"timeframe": "{{TimeFrame}}",
	"customerType": "{{CustomerType}}",
	"notes": "{{Notes}}",
	"additionalDetails": "{{AdditionalDetails}}",
	"price": {{OriginalPrice}},
	"discountedPrice": {{DiscountedPrice}},
	"trustedForm": "{{TrustedForm}}",
	"ipAddress": "{{IpAddress}}"
}

The resulting payload with fields inserted would look like:

{
	"firstName": "John",
	"lastName": "Doe",
	"address": "123 Test Street",
	"city": "Test City",
	"state": "IL",
	"zip": "00801",
	"phone": "(555) 555-5556 PIN: 0001",
	"directPhone": "5555555555",
	"email": "john.doe@test.com",
	"serviceID": 25,
	"craftjackLeadID": 111111,
	"created": "9/20/2017 12:00:00 AM +00:00",
	"serviceName": "Plumbing - Repair or Replace Faucets, Fixtures and Pipes",
	"serviceAreaName": "Test's Company - First Area",
	"serviceCategory": "Plumbing",
	"timeframe": "Within 2 weeks",
	"customerType": "Residential",
	"notes": "I am looking for someone to replace my faucets.",
	"additionalDetails": "Question: Is this an emergency? - Answer: No",
	"price": 25.0,
	"discountedPrice": 25.0,
	"trustedForm": "https://cert.trustedform.com/4eace04f",
	"ipAddress": "10.0.0.1"
}

Fields Recognized In the Custom Payload

Field Insertion Syntax Description Type
FirstName {{FirstName}} The lead's first name string
LastName {{LastName}} The lead's last name string
Address {{Address}} The lead's street address string
City {{City}} The lead's city string
State {{State}} The lead's state abbreviation string
ZipCode {{ZipCode}} The lead's zip code string
PhoneNumber {{PhoneNumber}}

The call tracking number for the lead, 

or direct phone number if call tracking is not enabled

 string
DirectLeadPhoneNumber {{DirectLeadPhoneNumber}} The direct phone number for the lead string
EmailAddress {{EmailAddress}} The lead's email address string
LeadId {{LeadId}} CraftJack's unique lead ID number
ServiceId {{ServiceId}} CraftJacks lead service ID number
ServiceName {{ServiceName}} Descriptive name of the service string
ServiceAreaName {{ServiceAreaName}} Descriptive name of the service area string
Service {{Service}} General service category string
TimeFrame {{TimeFrame}} Timeframe or urgency of the lead string
Notes {{Notes}} Any custom notes the lead provided string
CustomerType {{CustomerType}} Residential or Commercial string
ReceivedOn {{ReceivedOn}} The timestamp when the lead was received string
AdditionalDetails {{AdditionalDetails}} Additional details about the lead string
OriginalPrice {{OriginalPrice}} The original price of the lead number
DiscountedPrice {{DiscountedPrice}} The price after any promotional discounts have been applied number
TrustedForm {{TrustedForm}} The URL supplied by trusted form for tracking this lead string
IpAddress {{IpAddress}} The IP Address that the lead was submitted from string




Custom headers are additional pieces of information added to the standard headers in a web hook notification, typically consisting of a key and a value. For instance, a custom header might look like Authorization: Bearer YOUR_TOKEN or CustomField: CustomValue . These key-value pairs can be essential when integrating with platforms like Salesforce or other CRM systems. They ensure that the notification is processed correctly or authenticated, allowing for tailored interactions based on the receiving system's needs. You can optionally add these when setting up your custom formatting.


*Note, if you choose the content type of application/x-www-formurlencoded, all fields will be url encoded.

Still need help? Contact Us Contact Us

Related Articles