Webhooks
Updated at: Created at:
In this article we cover everything webhooks to include the following:
- How LeadByte clients use webhooks (with examples)
- How to create a webhook
- Webhook types explained with WHY you would use it
- Logs
- Q&A
How LeadByte clients use webhooks
The majority of our clients use webhooks to send event data in real-time to another end-point (often an app, crm, database). Zapier is a common end-point! Webhooks would mostly be used by technical users but the likes of Zapier have made it super simple to "catch a hook" and then automate a workflow.
Example 1 - Send sold leads to my reporting database each time a lead is sold
You have your own reporting system which pulls all your cost data from your ad networks (like Facebook). You need all revenue data (from LeadByte) so you can stitch together a P&L. You can create a webhook to trigger each time a lead is sold to include (for example) the buyer, the adGroup, adName and how much the lead was sold for.
Example 2 - I need to turn off my Google ads when a buyer cap has been reached
You may be running Google ads to generate leads for a specific client. When the cap has been reached for the buyer, you need to know so you can turn off your ads to avoid over spending. In this instance, you can create a webhook to Zapier to connect to your GA account and turn off your ads.
How to create a webhook & the different types
To create a webhook you need to navigate to Admin > Tech Hub > Webhooks as below animated image. Any webhooks that are listed in the Inactive tab will not fire. Listed below are all the possible webhooks with an explanation of each field. With every webhook you create you need to give it a reference; this is so you can identify the hook. This reference is available in the payload.
Webhook types explained
We have the following webhooks available for you to use. We advise that you always use the recommended webhook version. An example of the payload will be given against each webhook type. With all webhooks you need to enter in a URL: This is the request end-point
Export Schedule Triggered
This webhook will trigger when an export schedule runs or fails. This is commonly used by advanced / technical LeadByte clients that log in their own CRM export schedule activity.
Export schedules or enable for all: Here you select which schedule you want the webhook to be triggered against when the export schedule runs.
Fields for callback: These are the fields available to form part of the request payload data.
Only for failed export schedules: By enabling this you will only be notified if the export schedule fails. This is commonly used as it may act as the most important automation trigger for you to ensure all is working as expected.
Output timezone: Here you can change the date/time in the payload to a timezone of your choice.
Include reference in callback: By ticking this, the reference of the webhook is included in the payload.
Success response: Enter in what you determine to be a success response.
Example payload
{
"callbackType": "EXPORT-SCHEDULE_TRIGGERED",
"count": 1,
"records": [
{
"reference": "Test | Schedule | Email",
"release": "Hourly",
"runTime": "2022-03-21T12:05:16Z",
"scheduledRunTime": "2022-03-21T13:00:00Z",
"lastRunTime": "2022-03-21T11:09:52Z",
"recipients": [
"x@x.com"
],
"created": "2022-03-21T11:09:52Z",
"createdBy": "Anthony Burgin",
"captureMethod": "API, Import",
"fileFormat": "CSV",
"delimiter": ",",
"compression": "None",
"encryptionType": "",
"files": [
"487_21-03-2022.csv"
],
"errors": [],
"campaigns": [
{
"id": "613",
"name": "TEST",
"reference": "TEST"
}
],
"method": "Email",
"leadCount": "2"
}
]
}
Lead Sold/Unsold
This webhook will trigger when a lead is Sold, Unsold, Returned or Skipped against a campaign. This is commonly used by clients to signal to other apps that a lead has been sold. For example, a client running Facebook ads may use a tool like AnyTrack to capture sold leads from LeadByte and then update their Facebook account with a purchase event to then further target sold leads.
Campaign: Select the campaign(s) you want the webhook to trigger against when a lead is sold/unsold.
Delivery: Select the deliveries linked to the campaign you want the webhook to trigger against when a lead is sold/unsold.
Sold Status: Select what outcome you want to trigger against i.e. when a lead is sold, returned or unsold. The status skipped is when a lead is not allocated to a buyer.
Fields for callback: These are the fields available to form part of the request payload data.
Output timezone: Here you can change the date/time in the payload to a timezone of your choice.
Include reference in callback: By ticking this, the reference of the webhook is included in the payload.
Success response: Enter in what you determine to be a success response.
Example payload
{
"callbackType": "LEAD-SOLD_UNSOLD",
"count": 1,
"records": [
{
"deliveries": [
{
"id": 869,
"reference": "TEST 1",
"status": "Sent",
"delay": 0,
"scheduleTime": "2022-03-21T11:18:34Z",
"sentAt": "2022-03-21T11:18:34Z",
"responseLabel": "Success",
"rawResponse": "Thanks",
"validResponse": true,
"error": "",
"requestUrl": "https://go.webformsubmit.com",
"request": "email=x@x.com"
}
],
"lead": {
"id": 499917,
"email": "x@x.com",
"title": "Mr",
"firstname": "Anthony",
"lastname": "Smith",
"received": "2022-03-21T11:18:34Z"
},
"campaign": {
"id": 613,
"name": "TEST",
"reference": "TEST",
"currency": "GBP",
"deliveryModel": "Standard"
},
"supplier": {
"id": 93,
"name": "Supplier 1",
"sid": "2",
"status": "Valid",
"commission": "0.00",
"payoutType": "System Accept"
},
"buyers": [
{
"id": 67,
"name": "Buyer 1",
"reference": "154",
"status": "Sold",
"revenue": "50.00"
}
]
}
]
}
Lead Valid/Invalid
This webhook will trigger when a valid or invalid lead is received against a campaign. It is commonly used by clients that need to store a log of their lead activity in their own reporting CRM.
Campaign: Select the campaign(s) you want the webhook to trigger against when a lead is regarded as valid or invalid (system rejected).
Fields for callback: These are the fields available to form part of the request payload data.
Output timezone: Here you can change the date/time in the payload to a timezone of your choice.
Include reference in callback: By ticking this, the reference of the webhook is included in the payload.
Success response: Enter in what you determine to be a success response.
Example payload
{
"callbackType": "LEAD-VALID_INVALID",
"count": 1,
"records": [
{
"lead": {
"rejectionId": 24179,
"errorCode": "-2",
"errorMessage": "-2 | {\"response\":\"Lead was detected as being a duplicate.\",\"timestamp\":\"2022-03-21T11:17:50Z\",\"code\":-2,\"info\":[],\"leadId\":null,\"processTime\":0.63}",
"email": "x@x.com",
"title": "Mr",
"firstname": "Anthony",
"lastname": "Smith",
"received": "2022-03-21T11:17:50Z"
},
"campaign": {
"id": 613,
"name": "TEST",
"reference": "TEST"
},
"supplier": {
"id": 93,
"name": "Supplier 1",
"sid": "2"
}
}
]
}
SMS Sent
This webhook will trigger when an SMS is sent within a responder campaign. This is commonly used by technical data driven clients that have their own reporting CRMs.
Output timezone: Here you can change the date/time in the payload to a timezone of your choice.
Include reference in callback: By ticking this, the reference of the webhook is included in the payload.
Success response: Enter in what you determine to be a success response.
Example payload
{
"callbackType": "SMS-SENT",
"count": 1,
"records": [
{
"leadId": "499929",
"number": "44787xxxxxxx",
"body": "This is a test SMs with a link to click www.weboffers.co/dP/123456",
"timestamp": "2022-03-21T13:18:15Z",
"campaignId": 613,
"responderId": 133,
"pushId": 299,
"queueId": 3819,
"type": "Responder",
"triggerType": "Time Based",
"parts": 1
}
]
}
SMS Delivered/Undelivered
This webhook will trigger when an SMS link is delivered or undelivered within a responder campaign. This is commonly used by technical data driven clients that have their own reporting CRMs.
Output timezone: Here you can change the date/time in the payload to a timezone of your choice.
Include reference in callback: By ticking this, the reference of the webhook is included in the payload.
Success response: Enter in what you determine to be a success response.
Example payload
{
"callbackType": "SMS-DELIVERED_UNDELIVERED",
"count": 1,
"records": [
{
"status": "Delivered",
"leadId": 499929,
"number": "44787xxxxxxx",
"timestamp": "2022-03-21T13:18:17Z",
"campaignId": 613,
"responderId": 133,
"pushId": 299,
"queueId": 3819,
"type": "Responder",
"triggerType": "Time Based"
}
]
}
SMS Link Clicked
This webhook will trigger when an SMS link is clicked within a responder campaign. This is commonly used by technical data driven clients that have their own reporting CRMs.
Output timezone: Here you can change the date/time in the payload to a timezone of your choice.
Include reference in callback: By ticking this, the reference of the webhook is included in the payload.
Success response: Enter in what you determine to be a success response.
Example payload
{
"callbackType": "SMS-LINK_CLICKED",
"count": 1,
"records": [
{
"leadId": 499929,
"timestamp": "2022-03-21T13:18:20Z",
"campaignId": 613,
"responderId": 133,
"pushId": 299,
"queueId": 3819,
"type": "Responder",
"triggerType": "Time Based"
}
]
}
User Alert
This webhook is linked to campaign alerts. If you want to send a webhook as well as an email when an alert is triggered, you need to create this type of webhook.
Output timezone: Here you can change the date/time in the payload to a timezone of your choice.
Include reference in callback: By ticking this, the reference of the webhook is included in the payload.
Success response: Enter in what you determine to be a success response.
Example payload
{
"callbackType": "USER-ALERT",
"count": 1,
"records": [
{
"rule_name": "TEST WEBHOOK",
"rule_id": "L9",
"timestamp": "2022-03-21 13:24:16",
"trigger_webhook_id": [
"91"
]
}
]
}
Feedback Added
This webhook will trigger when feedback from a buyer has been added to a lead.
Fields for callback: These are the fields available to form part of the request payload data.
Output timezone: Here you can change the date/time in the payload to a timezone of your choice.
Include reference in callback: By ticking this, the reference of the webhook is included in the payload.
Success response: Enter in what you determine to be a success response.
Example payload
{
"callbackType": "FEEDBACK-ADDED",
"count": 1,
"records": [
{
"lead_id": "499931",
"buyer_id": "67",
"buyer_name": "Buyer 1 (154)",
"username": "CD1234",
"timestamp": "2022-03-21T13:23:53Z",
"feedback": "Buyer Duplicate",
"feedback_note": "Sorry, refund please"
}
]
}
Logs
Logs provide you with all the webhook activity. If you are not receiving any requests to your URL end-point (CRM, Zapier etc) you can use logs to see if the request was made and what the response was from the end-point.
Q&A
I want to see the payload before I go live, how can I see this?
You will need to use a service like https://webhook.site/ to capture the request so you can see the payload.
Comments