Webhooks
Incoming webhooks for leads and applications and outgoing webhooks that send changes from Leadmode to your system, with structure, signature and limits.
Webhooks come in two directions. Incoming webhooks are addresses to which another system sends data by POST, for example a website form, a Meta or Google ad, Make, Zapier, n8n or your AI. Outgoing webhooks send changes from Leadmode to a system of yours, for example a table, a customer portal or an automation. You find both under Settings → Integrations → More integrations → Webhooks. The page distinguishes Incoming and Outgoing; the sections up to "Sending applications" describe the incoming ones, from Outgoing webhooks onwards the outgoing ones.
The CRM module must be active. Addresses for projects, funnels and landing pages are created by the project lead or an organisation admin. Leads sent are created in the name of the person who created the address, as long as they are a member of the organisation.
Which addresses there are
The page "Webhooks" shows tiles. For each tile you create addresses.
| Tile | Where the enquiries go |
|---|---|
| General lead intake | as a lead into a project, without page or position |
| Funnels | as a response to one of your funnels; counts in its analysis |
| Landing pages | as an enquiry to one of your landing pages; counts in its analysis |
| Applications | as an application for a position or as an unsolicited application to the recruiting board, stage "New" |
For funnels, landing pages and applications the list shows for each entry the status ("Not set up", "Webhook active", "Paused") and the number of entries. With Create you generate the address. Afterwards you copy the URL with Address or a ready-made text for your AI with Guide for AI. Details opens the page on which the address is managed: the funnel or landing page (area "External connection (webhook)") or the position in recruiting.
For each funnel, landing page and position there is at most one address. For a project you can create as many as you like with Create another address, for example one per source.
The address and the secret
The address contains a secret token. No further access data is needed. Pass the address only to systems that are meant to send.
Leads: POST https://<YOUR-LEADMODE-ADDRESS>/api/public/leads/<ORGANISATION>/<SECRET>
Applications: POST https://<YOUR-LEADMODE-ADDRESS>/api/public/applications/<ORGANISATION>/<SECRET>You copy the finished address from the interface. With Generate new address the token is replaced; the old address stops working immediately, and you must enter the new one in all systems. With the switch (Active or Paused) you pause an address. When deleting, sending systems receive an error; leads and applications already created remain.
Send leads
Content-Type: application/json or application/x-www-form-urlencoded. Size up to 200 KB. Browser forms on other sites may call the address.
curl -X POST 'https://<YOUR-LEADMODE-ADDRESS>/api/public/leads/<ORGANISATION>/<SECRET>' \
-H 'Content-Type: application/json' \
-d '{ "name": "Anna Beispiel", "email": "anna@beispiel.de", "phone": "0171 1234567", "company": "Beispiel GmbH", "message": "Bitte um Rückruf", "externalId": "anfrage-4711" }'Fields
email or phone is required. Everything else is optional. Common names such as first name, last name, phone, company or message are recognised by Leadmode itself, as is the format of Meta Lead Ads.
| Field | Meaning |
|---|---|
name or firstName and lastName | name |
email, phone | email, phone |
company, jobTitle, website | company, position, website |
street, postalCode, city | address |
message | free text, concern |
externalId | own identifier of the enquiry; prevents duplicates on repetition |
utm_source, utm_medium, utm_campaign, utm_term, utm_content | origin of the ad |
trackingConsent | Explicit permission to track the request (true/false, yes/no). Leadmode only stores the identifiers below when it is true |
fbclid, fbc, fbp, gclid, adId | click and ad identifiers; stored only with tracking permission |
All further fields Leadmode appends to the message as lines "Field: value" (up to 30 fields). Invalid email addresses, phone numbers and websites are left out by Leadmode instead of discarding the lead. If neither a valid email nor a valid phone number remains, the enquiry is rejected.
If Leadmode does not recognise a field, you assign it in the project lead entry under "Unmapped fields in the latest receipt" to a target, or choose "Do not use". The assignment applies to all future entries. Under "Latest receipts" you see the last 20 enquiries with what was recognised. With Send test lead you send a test lead ("Test lead webhook") that you can delete later.
Responses
| Response | Meaning |
|---|---|
201 {"status":"created"} | new lead created, with task "New lead – call" |
200 {"status":"returning"} | the person already exists in the project (same email address, or without email the same phone number). Leadmode creates the task "Repeat enquiry – call back" on the existing lead, but no second card. |
200 {"status":"duplicate"} | exactly this enquiry arrived before. Nothing created twice. |
422 {"status":"rejected","error":"…"} | no valid email and no valid phone number; the message gives the reason |
400 | data neither as JSON nor as a form |
404 | address invalid, paused or deleted |
429 | too many enquiries; send again later |
Duplicate enquiries
Leadmode remembers the enquiries for each address. With externalId only this identifier counts. Without it, Leadmode compares the content (fields with time or date information are excluded). Sending the same enquiry twice is therefore harmless.
Origin class and source
Each lead receives an origin class: Cold, Warm or Website. When creating a project address you choose the source (for example "Website form", "Meta Ads (Facebook, Instagram)", "Google Ads", "LinkedIn", "Webinar", "Referral", "Warm enquiry", "Other") and the origin class; the source suggests a matching class. For funnels and landing pages, project, source, origin and owner come from the page. Who receives the new tasks depends on the owner set, otherwise on the project lead.
Send applications
The same technique, another address and other fields. On the position in recruiting you find them under "External connection (webhook)" with Create application address. See also Recruiting.
curl -X POST 'https://<YOUR-LEADMODE-ADDRESS>/api/public/applications/<ORGANISATION>/<SECRET>' \
-H 'Content-Type: application/json' \
-d '{ "firstName": "Lena", "lastName": "Bergmann", "email": "lena@beispiel.de", "phone": "+49 30 123456", "message": "Ich bewerbe mich als Telefonvertriebler.", "file": { "name": "Lebenslauf.pdf", "content": "<BASE64-DER-DATEI>" } }'| Field | Meaning |
|---|---|
firstName and lastName (or name) | required |
email | required |
phone | optional |
message | cover letter, optional |
file | optional: name and content (Base64). PDF, Word, images and OpenDocument up to 5 MB. With form transmission without a file. |
Further fields land as lines "Field: value" in the note of the application.
| Response | Meaning |
|---|---|
201 {"status":"created"} | application created |
200 {"status":"duplicate"} | the same email address has already applied for this position in the last 30 days |
422 | details incomplete; the message says what is missing |
400 | file empty, too large or wrong file type |
404 | address invalid, paused, deleted, or the position is no longer open |
429 | too many enquiries |
Outgoing webhooks
An outgoing webhook sends a POST with JSON to the address of your target system when changes occur in Leadmode. For example, a project table stays up to date without manual copying. You find it under Settings → Integrations → More integrations → Webhooks → Outgoing.
Project areas are set up by the project lead or an organisation admin. Areas without a project reference and sensitive areas such as billing, recruiting and team are set up by organisation admins only.
Set up
New webhook opens a dialogue with six steps. With Next and Back you move between them; at the end Create webhook creates it.
| Step | What you set |
|---|---|
| Target | name, project (or "Entire organisation") and the address of the target system. Only https:// addresses are allowed. |
| Areas | what is sent, for example lead, opportunity, task, appointment, activity or invoice. With Search area you filter the list. A webhook with a project sends only areas of the project; one without a project sends only areas of the organisation. |
| When | on Newly created, Changed and Deleted. For "Changed" you can narrow down to certain fields and a condition. The quick choice offers ready-made settings. For each area you can adjust this individually. |
| Content | the fields per area that are sent. The usual ones are preselected. |
| Lead | additional details about the lead, also Custom fields of the lead, and options. |
| Check | summary and creation. |
Under Further options you decide whether imports and changes made by webhooks and AI are also sent. By default both stay quiet: an import file with a thousand rows should not overwhelm your target system, and changes that come from a webhook or the AI itself should not trigger loops.
After creation the webhook shows under Access and test the signing secret (with Renew), Send test and Guide for recipients. The guide is a finished text for your target system or AI with format, headers, signature check and examples. Below it the log shows the latest deliveries. With the switch in the list you pause a webhook; Delete removes it including the log.
Structure of a delivery
Each delivery is a POST with Content-Type: application/json. The body contains:
| Field | Meaning |
|---|---|
id, event, occurredAt | identifier of the delivery, event name (for example opportunity.update) and time |
area, operation | area and operation (insert, update, delete) |
projectId, objectId, contactId | project, changed record and associated lead |
origin, actor | origin of the change (for example manual or import) and the changing person as an identifier |
data | the chosen fields with the value after the change; for "Deleted" with the last value |
changes | changed fields with before and after |
contact | optional, the chosen details about the lead; custom fields under custom_fields |
Amounts are amounts in cents, date values ISO 8601 in UTC. Employees appear as an identifier, stages and statuses as keys.
Check the signature
Each delivery carries four headers:
X-Leadmode-Delivery: unique number of the delivery; the same on repetitionsX-Leadmode-Event: the event nameX-Leadmode-Timestamp: Unix time in secondsX-Leadmode-Signature:sha256=and the HMAC-SHA256 (hex) over<Timestamp>.<raw body>with the signing secret
To check it: read the raw body unchanged, calculate the HMAC with the secret and compare it with the value after sha256=. Timestamps older than five minutes are rejected.
Responses and repetitions
Your system answers with a 2xx status, ideally within ten seconds. Anything else counts as an error. For errors, 408, 425, 429 and 5xx, Leadmode sends again with growing pauses (30 seconds to 6 hours, at most eight attempts). Other 4xx responses count as final. After 25 consecutive errors the webhook pauses, and the interface shows the reason.
The order is not guaranteed; occurredAt shows which change is newer. A delivery may arrive more than once. Recognise duplicates by X-Leadmode-Delivery.
Leads, contact persons and phone numbers
A lead belongs to your organisation and sits in all projects in which you manage it, with the same master data, contact persons and contact channels. If the lead, a contact person or a contact channel changes, each subscribed project in which the lead appears sends exactly one event. objectId and contactId contain the identifier of the lead in this project. Contact persons and contact channels keep the identifier your system already knows for them in this project. What is newly created carries the identifier that is the same in all projects. This shared identifier is also supplied by the fields Identifier on the lead (lead_person_id, lead_channel_id) if you choose them in the step "Content". Leads without a project send nothing. A contact person can trigger two events when saved; the first changes only the field "Main contact person".
Finance events
Finance also reports events. Only organisation admins set them up. Quotes, orders, invoices and their payments belong to a project and therefore go to webhooks with a project. All other finance areas have no project reference and go to webhooks for the entire organisation.
| Area | Quick choices |
|---|---|
| Quote / order / invoice | document issued, quote accepted |
| Payment | payment recorded |
| Incoming receipt | receipt submitted, status changed, approved, rejected |
| Payment on incoming receipt | payment on receipt recorded |
| Bank transaction | bank transaction imported |
| Assignment of a bank transaction | bank transaction assigned, assignment removed |
| Subscription (recurring expense) | subscription created, paused, resumed or ended |
| Collective billing of expenses | status changed, submitted, approved, rejected, expenses reimbursed |
Only key data such as number, status, amount in cents, currency and date are sent. Names, notes, positions, addresses and bank data such as IBAN are stored encrypted and are not sent. The journal itself reports nothing, because it is a consequence of the invoices, payments and approvals, which you can already subscribe to individually.
A typical use: you send "Receipt approved" to your wiki or to Slack, or "Payment recorded" to your project management tool, so that the status matches there. Do not recalculate in your system, but take over the amounts as they arrive.
Report bookings from customers
In the area Appointment the quick choice Appointment booked reports every new appointment, and Customer booked themselves only those that a customer created themselves via a booking page or a booking link (booking_channel is self). The field Booking page (booking_page_id) names the page; as a condition or filter a single page can be singled out. In addition, time, type, owner and, via the contact fields, the name and email address of the customer can be sent along. Bookings by customers count as an automation of the organisation: you do not need to switch on Webhooks and AI under "Further options" for them.
Reporting results back to a measurement system
To report results back to a measurement system later (for example qualified, first meeting held, won), select the details of the original request in the “Lead” step: tracking permission (tracking_consent, tracking_consent_at), request ID (tracking_request_id), ad source (tracking_source), the UTM values (utm_source, utm_medium, utm_campaign, utm_term, utm_content) and the click and ad identifiers (tracking_fbclid, tracking_fbc, tracking_fbp, tracking_gclid, tracking_ad_id, tracking_external_lead_id). They appear under contact in the events for lead, opportunity and appointment.
These values come from the first request through a lead webhook or landing page and stay unchanged when the person asks again. Imported, cold-called or manually created leads have none. The identifiers are only filled when the request explicitly carried the permission (trackingConsent). Only send to the measurement system when tracking_consent is given and origin_class is website.
Send block reports to a table
The area Block report reports every confirmed or corrected version of a report on a call block. The quick choices are called "Block report confirmed" and "Block report corrected". Choose the webhook with the project, so that only this project sends.
Sent are the report identifier (event_id), the version (revision), the status (status: confirmed or corrected), the counters of the report and the times in minutes. The text of the report is not included. Your target system takes event_id as the key and accepts a delivery only if its revision is higher than the stored one. This way nothing is added twice, even if a delivery arrives several times or in the wrong order. A confirmed report cannot be withdrawn; a correction replaces incorrect data.
Decline details on results
For an email result, the Activity area can also send: the email the result refers to (mail_id), the decline reason (decline_reason, only for results in the Decline group: exclusive contract, existing provider, internal solution, no need, no capacity, other), the named provider (provider_name) and the provider's contract end: precision (contract_end_precision: day known, month and year known, month only, unknown), contract end (contract_end_on) and contract end as month only (contract_end_month). All fields are empty if nothing was named. The contract end is not permission to make contact; do not derive any outreach from it. Webhooks for groups do not send the decline reason or the other decline details.
Funnels and landing pages
The Funnel lead area reports answers from funnels and landing pages. The presets are "New funnel lead" and "Lead completed". If a visitor enters their contact details first and answers further questions afterwards, the funnel lead is created with the status Incomplete. With the last answer it changes to Complete, Completed at is set, and "Lead completed" fires. Funnels without follow-up answers start directly as "Complete".
You can also send: Points (quiz) (points), Highest score (quiz) (points_max), Funnel version (quiz) (funnel_version; points from different versions are not comparable), Origin page (origin_page, the landing page the visitor came from), Status (completion) and Completed at (completed_at). The individual answers and a funnel's statistics counters are not sent.
Project staffing
The Project staffing (person in the project) area has the field Own leads only (own_only): the person sees only leads they created themselves. The quick choice "Project role or own-leads-only changed" reports a change to it.
What is not sent
Not released are access data and tokens, chat, journal, chart of accounts and accounting settings, call recordings and transcripts, compensation, staff data and internal queues. Rows without a project, for example personal tasks, do not trigger project webhooks. Addresses in the internal network or without https:// are rejected by Leadmode; redirects are not followed.
What you send to your target system is subject to its data protection. Choose only the fields your system needs.
Limits
For incoming webhooks the following applies:
- Leads: at most 120 enquiries per minute and sender address, and 600 per ten minutes per webhook address. Repeatedly invalid addresses temporarily block the sender.
- Applications: at most 300 enquiries per ten minutes per address.
- Leadmode stores the last 20 entries per lead address for display.
- The limits of the outgoing webhooks are in the section Outgoing webhooks.