1. What Are Webhooks?
Webhooks let LeadEngine push or receive real‑time data using simple HTTPS requests. Think of them as automated data couriers:
Outbound (Event Triggers) – LeadEngine ➜ Your tool when something happens (e.g., a lead’s status changes to Opportunity).
Inbound (Create / Update) – Your tool ➜ LeadEngine when you send lead records in.
2. Outbound Webhooks (Event Triggers)
2.1 When They Fire
Outbound webhooks are sent each time the Lead Status on a record changes (e.g., Conversation ➜ Needs Info). The payload includes:
New & previous lead status
All LeadEngine default fields (plus your custom fields)
Threaded message history for context
Workspace & campaign names
2.2 Supported Lead Statuses
Follow Up, Needs Info, Conversation, Opportunity, Not Interested, Do Not Contact,
Unsubscribe, Auto Reply, Hard Bounce, Soft Bounce, Out of Office, Unknown,
Wrong Contact, Meeting Booked
2.3 Sample Payload
{
"new_lead_status": "Needs Info",
"lead_name": "Elon Musk",
"lead_email_address": "elon@x.com",
"workspace_name" :"My Default Workspace",
"campaign_name": "My Super Performing Campaign",
"customFields": [
{
"value": "Elon Musk",
"key": "name"
},
{
"value": "Elon",
"key": "first_name"
},
{
"value": "Musk",
"key": "last_name"
},
{
"value": "elon@gmail.com",
"key": "email"
},
{
"value": "elon@x.com",
"key": "business_email"
},
{
"value": [
"Prospect",
"Cars",
"Space"
],
"key": "tags"
},
{
"value": "2024-12-02T14:05:38Z",
"key": "created_date"},
{
"value": [
"My Super Performing Campaign",
"Newsletter"
],
"key": "campaigns"
},
{
"value": "Gmail",
"key": "email_provider"
},
{ "value": 1,
"key": "my_custom_number_field"
}
],
"messages": [
{
"angle": "Autogrow",
"framework": "Problem, Solution, Proof, CTA",
"test": "a",
"body": "Full body of the first threaded message.",
"tone": "Informal",
"from": {
"name": "LeadEngineUser",
"address": "user@leadengine.ai"
},
"campaign_step": 1,
"word_limit": 225,
"type": "outbound",
"subject": "First message subject",
"to": {
"name": "Elon Musk",
"address": "user@leadengine.ai"
},
"date": "2025-05-06T08:58:10Z"
},
{
"body": "Full body of the message response",
"from": {
"address": "elon@x.com",
"name": "Elon Musk"
},
"type": "inbound",
"subject": "Re: First message subject",
"to": {
"address": "user@leadengine.ai",
"name": "LeadEngineUser"
},
"date": "2025-05-06T08:59:17Z"
},
{
"body": "Autoreply message body",
"to": {
"name": "Elon Musk",
"address": "elon@x.com"
},
"date": "2025-05-06T08:59:22Z"
...
...
...
...
}
],
"previous_lead_status": "Conversation"
}
2.4 How to Create an Outbound Webhook
Navigate: Settings ▸ Webhooks
Click
Add Trigger under “Send Data” Name the webhook
Give it a description
5. Choose Trigger: Lead Status Updated
6. Paste the destination URL your receiving tool gives you.
7. Save & Test. Use Send Test to fire a sample payload instantly.
3. Inbound Webhooks (Create / Update Leads)
Need to push leads into LeadEngine from forms, CRMs, or Zapier? Use an Inbound webhook.
How to Create an Outbound Webhook
Navigate: Settings ▸ Webhooks
Toggle to “Receive Data”
Click
Add Action Name the webhook
Give it a description
Optional: Select a list to add the updates lead into.
During setup you’ll map incoming keys ➜ LeadEngine fields.
Select a property in LeadEngine to map on the left
Enter the value String using the naming structure guides from the platform you’re sending from.
Repeat this until all your fields are mapped.
Data Stucture:
Flat:
email➜ business_emailNested:
contact/work/email➜ business_email (use/as the path separator)Multi‑value arrays are supported.
Copy the Webhook URL & Paste it into the 3rd party tool you’re connecting
9. Endpoint & Auth
Endpoint –
https://webhooks.leadengine.ai/<YOUR_UNIQUE_WEBHOOK_ID>Method –
POSTAuth – HTTP header
Create an API key for the platform you’re sending data from
Copy the API key and paste it into the Authorization Bearer Token in the platform you’re connecting.
3.3 Sample Inbound Payload
{
"first_name": "Lead",
"last_name": "Engine",
"name": "Lead Engine",
"email": "test@leadmagnets.io",
"phone": "15555555555",
"city": "Minneapolis",
"state": "Minnesota",
"country": "United States",
"date": "2024-10-02T15:28:20Z"
}4. Default LeadEngine Fields
Here’s a master list of the default LeadEngine fields you can map:
about, business_email, campaigns, city, company_facebook, company_linkedin, company_name,
company_x, contact_owner, country, created_date, business_email, personal_email, email_bounce_status,
email_bounce_sub_status, email_provider, email_provider_type, email_subscription,
email_validation, first_name, gender, import_tags, industry, job_department,
job_title, last_contacted, last_email_click_date, last_email_open_date,
last_email_reply_date, last_name, lead_source, lead_status, lead_status_history,
lead_type, life_cycle, life_cycle_history, person_linkedin, linkedin_summary, lists,
mobile_phone, modified_date, name, number_of_email_clicks, number_of_email_opens,
number_of_email_replies, number_of_emails, number_of_employees,
number_of_phone_calls, number_of_sms_replies, number_of_sms_sent,
number_of_times_contacted, office_phone, person_facebook, person_x, phone_country,
phone_validation, postal_code, sentiment, sentiment_history, sms_subscription,
state, street_address, tags, time_zone, website, website_summary5. Testing & Troubleshooting
|
| IssueLikely CauseFix |
401 Unauthorized | Missing/invalid API key | Re‑generate key in Settings ▸ API Keys |
404 Not Found | Wrong webhook ID | Copy the exact ID shown in Webhook details |
No data arriving | Mapping mismatch | Use Send Test and inspect the request in the target tool |
Duplicate leads | Field used for deduping not mapped | Map business_email or another unique ID |
6. Best Practices
Test first. Always fire a Send Test before going live.
Use separate webhooks per environment (staging vs prod) for easier debugging.
Secure your endpoint. Accept only requests from LeadEngine IPs or validate the shared secret.
Log failures. Your receiving server should return 2xx on success; LeadEngine will retry transient 5xx errors.
7. FAQs
Q: How many webhooks can I create?
A: Unlimited webhooks.
Q: Can I filter outbound triggers by list or campaign?
A: Yes—add optional Filters in the webhook settings panel.
Q: Does LeadEngine retry failed outbound webhooks?
A: We retry up to 5 times using exponential back‑off (≈90 minutes total).
Need Help?
If your webhook isn’t behaving, message us in‑app or email support@leadengine.ai with the webhook ID and timestamp of the last attempt.
Happy automating 