Booking Delivery Webhooks

Our booking delivery webhooks are designed to be used by our strategic accounts to enable them to get details of checkatrade jobs (bookings) 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

Booking webhooks will be triggered in two stages

Booking delivery webhooks operate differently from lead delivery webhooks as they are triggered twice for each job and will include trade web app url for easy access of the particular job :

Job Created Stage: Triggered when a job is initially requested from a tradesperson
Job Booked Stage: Triggered when the job is booked with a tradesperson

The Request Object

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

Job Booking Object:

Field	Type	Description	Job Created	Job Booked
`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.	✅	✅
`customerEmail`	STRING	The email address of the Customer associated to the Job.	❌	✅
`address`	Address	The physical address of the Customer associated to the Job.	❌	✅
`customerPhone`	STRING	The phone number of the Customer associated to the Job.	❌	✅
`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 • REQUEST_A_QUOTE	✅	✅
`status`	STRING	The job status, whether BOOKED or REQUESTED	✅	✅
`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.	✅	✅
`tradeWebUrl`	STRING	The trade web app url for the specific job. https://membersapp.checkatrade.com/jobs/jobId	✅	✅

Address Object:

Field	Type	Description
`postcode`	STRING	The postcode of the address
`line1`	STRING	The first line of the address
`line2`	STRING	The second line of the address (nullable)
`line3`	STRING	The third line of the address (nullable)
`city`	STRING	The city or town
`uprn`	STRING	Unique Property Reference Number for the address

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 Payloads

Job Created Stage Example

{
  "jobId": "job-uuid-12345",
  "category": "Solar Panels",
  "title": "Solar panels fitted - SW1A 1AA",
  "jobDescription": "Looking to have solar panels installed on a 3-bedroom house roof",
  "customerName": "John Smith",
  "dateCreated": "2024-07-16T16:46:12.707Z",
  "preferredStart": {
    "option": "Within 2 weeks",
    "date": null
  },
  "source": "QUOTE_REQUEST",
  "additionalInformation": [],
  "postcode": "SW1A 1AA",
  "leadEnrichment": {
    "questions": []
  },
  "media": [],
  "tradeWebUrl": "https://membersapp.checkatrade.com/jobs/job-uuid-12345"
}

Job Booked Stage Example

{
  "jobId": "job-uuid-12345",
  "category": "Solar Panels", 
  "title": "Solar panels fitted - SW1A 1AA",
  "jobDescription": "Looking to have solar panels installed on a 3-bedroom house roof",
  "customerName": "John Smith",
  "customerEmail": "[email protected]",
  "customerPhone": "+447123456789",
  "dateCreated": "2024-07-16T16:46:12.707Z",
  "preferredStart": {
    "option": "Within 2 weeks", 
    "date": null
  },
  "source": "QUOTE_REQUEST",
  "additionalInformation": [],
  "postcode": "SW1A 1AA",
  "leadEnrichment": {
    "questions": []
  },
  "media": [],
	"address": {
    "postcode": "SW1A 1AA",
    "line1": "1 Tarragon Drive",
    "line2": null,
    "line3": null,
    "city": "Guildford",
    "uprn": "100061403999"
  },
  "tradeWebUrl": "https://membersapp.checkatrade.com/jobs/job-uuid-12345"
}