Lead Delivery Webhooks

Our lead delivery webhooks are designed to be used by our strategic accounts to enable them to get details of checkatrade jobs (leads) passed straight into their systems. If you want to start making use of these webhooks please reach out to your account manager.

How to proceed with the integration

To set up this integration, please follow these steps:

Read this documentation
Send your webhook URL to your Checkatrade Account Manager
Whitelist the IPs (if necessary)
We will then configure the integration and send over a test payload
Map the fields from the payload into your CRM

The Request Object

Below is a breakdown of the response JSON object providing an overview of what each field means.

Lead Object:

Field	Type	Description
`jobId`	STRING	A job ID is a unique identifier assigned to a specific job, used to track and distinguish it from other jobs within the system.
`category`	STRING	A job category is a classification of the type of job within the Lead.
`title`	STRING	The main title of the job. E.g. "Solar panels fitted".
`jobDescription`	STRING	A more in depth breakdown of the kind of work the Customer is looking to have completed.
`customerName`	STRING	The name of the Customer looking to have the job done.
`customerPhone`	STRING	The phone number of the Customer associated to the job.
`customerEmail`	STRING	The Customers email address.
`dateCreated`	STRING	The date the job was created in ISO 8061 as mentioned on RFC3339.
`preferredStart`	PreferredStart	The description of how urgent the Job needs to be addressed from the Customer. See PreferredStart object below.
`source`	STRING	The source of the job. Example: • DIRECT_MESSAGE • QUOTE_REQUEST
`additionalInformation`	[AdditionalInformation]	An array of objects consisting of questions and answers referring to the Job.
`postcode`	STRING	The Customers postcode.
`leadEnrichment`	LeadEnrichment	A JSON object containing questions and answers asked of the consumer in a new format. Please Note: 1. You will only receive `leadEnrichment` data if we have updated you to the latest version of our webhooks. Speak to your account manager about updating. 2. You will only get `leadEnrichment` data if we have asked the consumer for it and we are running experiments on this at the moment so not all consumers are being asked for this info yet.
`media`	STRING[]	An array of strings which are URLs to images the consumer has attached to the job. Please Note: You will only receive `media` data if we have updated you to the latest version of our webhooks. Speak to your account manager about updating.

Preferred Start Object:

Field	Type	Description
`option`	STRING	The human readable format of the preferred start date. Example: • "In planning" • "Within a few days"

Additional Information Object:

Field	Type	Description
`question`	STRING	The additional question that has been added to the Job.
`answer`	STRING	The answer to the additional question on the Job.

LeadEnrichment Object:

Please Note:

You will only receive leadEnrichment data if we have updated you to the latest version of our webhooks. Speak to your account manager about updating.
You will only get leadEnrichment data if we have asked the consumer for it and we are running experiments on this at the moment so not all consumers are being asked for this info yet.

Field	Type	Description
`questions`	Question[]	This array contains all the questions and answers to the questions, if all questions are marked as not-required this array can be empty but never null.

Question object:

Field	Type	Description
`title`	STRING	The question that was asked of the consumer
`format`	ENUM	Tells you the type of question that was asked and informs your system how to display the answers. ENUM values: • "SINGLE_SELECT" • "MULTI_SELECT" • "SINGLE_SELECT_VISUAL" • "MULTI_SELECT_VISUAL" • "TEXT"
`answers`	Answer[]	Contains a list of the answers provided along with additional parameters. For a SINGLE_SELECT question this will only contain one answer object whereas for MULTI_SELECT questions this will contain however many the user selected

Answer Object:

Field	Type	Description
`key`	string	Generated based on value and parsed to kebab-case format.
`value`	STRING \| NUMBER \| NULL	The text show in on the option chosen by the consumer, e.g. for window colours: "white", "brown" or ranges like min and max value

The Response

The webhook has a response type of 201. Sending this response to the webhook endpoint confirms a successful receipt and acknowledgement of the data transmitted.

Example Payload

{ 
"jobId":"Jp8XsbVDzR0NuAlC3pg3", 
"category":"Windows/Doors/Conservatories", 
"title":"UPVC Window Installation in PO6 3EN", 
"jobDescription":"I'm looking for new double-glazing windows for the front of my house", 
"customerName":"Joe Bloggs",
"customerPhone":"01234556789", 
"customerEmail":[email protected], 
"dateCreated":"2023-05-16T14:35:50.432479+00:00", 
"preferredStart":{ "option":"Within 2 weeks"}, 
"source":"DIRECT_MESSAGE", 
"additionalInformation":[ { "question":"How many windows need to be installed?", "answer":"3" } ] 
"postcode":"PO6 3EN",
"leadEnrichment":
{
    "questions": [
        {
            "answers": [
                {
                    "key": "yes",
                    "value": "Yes, I own it"
                }
            ],
            "format": "SINGLE_SELECT",
            "questionId": "ownership-status-default",
            "title": "Do you own the property?"
        },
        {
            "answers": [
                {
                    "key": "toilet",
                    "value": "Toilet"
                },
                {
                    "key": "shower",
                    "value": "Shower"
                }
            ],
            "format": "MULTI_SELECT",
            "questionId": "24WRnR0rLx4CRh4k82evY6",
            "title": "What's the work needed on?"
        },
    ],
},
"media": ["https://someurl.com","https://someurl2.com"]
}

Other Info

Checkatrade reserve the right to add extra fields into the payload, therefore please implement this in a way that the presence of additional fields will not break your integration. We will notify you with advanced warning if we plan to remove or modify any existing fields within the payload. Please be aware that the values within category are subject to change as we enhance the funnelling and lead categorisation.

Static IPs

Static IP addresses enhance webhook security by allowing for easy verification of incoming requests and preventing unauthorised access. This helps secure the transmission of data and reduces risk of malicious activities.

For Checkatrade's API there are two main static IP addresses:

Note the old IP addresses are only used for existing trades, if you are new to our webhooks you only need to whitelist our new IPs.

Environment	IP Address	Description
Development	Old: 35.242.163.176 (existing trades only) New: 34.105.162.121 34.89.85.173 35.234.151.94	This is the main test environment which can be used when initially integrating for validation testing.
Production	Old: 34.142.46.71 (existing trades only) New: 35.246.15.126 35.242.187.239 34.39.18.129	Main IP address to receive live active leads.

Security

Currently the main security around this Webhook is based on API whitelisting. This is subject to change for more advanced security.

Billing

At Checkatrade we will bill you for the leads we send via their unique IDs at our side. It may be that leads are sent multiple times to a customer's system (in edge cases) they will have a unique ID for de-duplication. Invoices will have this covered and should you provide a receipt ID we will be able to create a report on this for you.