Skip to main content
The Custom Webhook accepts a lead pushed into DeltaLead from an external system. One route, one purpose, one required header. For dashboard key creation and the difference between key modes, see the Custom Webhook guide.

​
Endpoint

​
Authentication

Send your key as a bearer token:
The scheme is matched case-insensitively and the token is trimmed, so bearer dl_live_abc is accepted. The key identifies both the account and the mode — nothing else in the request selects them.
A missing header, a malformed header, an unknown key, a revoked key, and an expired key all return the same 401 unauthorized response. The bodies are identical by design: a caller cannot use the error to learn whether a given key exists.

​
Request Body

The body is a JSON object with a single lead key. Lead contract v1 requires lead.name, plus at least one of lead.email or lead.phone. Missing either condition returns 400 missing_required_fields.
​
string
required
Full name of the lead. DeltaLead splits it at the first space: everything before becomes the first name, everything after becomes the surname. "María García" gives María / García, and "Probe Alpha Betamax" gives Probe / Alpha Betamax.The split is positional, not linguistic, so a compound given name lands in the surname field — "María José García" gives María / José García. If your system already stores given and family names separately, join them with a single space in that order rather than sending a display name.
​
string
Email address. Required unless lead.phone is present.
​
string
Phone number. Required unless lead.email is present. E.164 format is recommended, e.g. +5491155551234.
​
string
Free-form origin label for the delivery, e.g. landing-page. Recorded on the lead and used by downstream processing — it appears in the lead’s AI summary. Every delivery through this endpoint is reported on the lead as the Custom channel regardless of what you send here, so use source to distinguish which of your systems produced the lead.
​
string
Free-text description of the vehicle the lead asked about, e.g. Toyota Hilux SRX 2024. Recorded on the lead and used by the AI summary to match against catalogue stock, so send what the buyer actually wrote rather than an internal stock code.
​
string
Free-text context from your side. Appended to the lead’s Notas, attributed to the webhook, and visible to the advisor. Deduplicated per delivery, so a retry does not add the same note twice.
​
object
Arbitrary JSON object stored on the lead as passthrough, merged across deliveries rather than overwritten. Use it for identifiers from your own system that have no home in the contract. Nothing in DeltaLead interprets it and it is never shown to the AI agent. Keys containing . or $ are rejected.
These seven fields are the entire contract. Any other key inside lead is accepted — the request still returns 200 — but it is discarded and never reaches the lead record. Anything outside the contract belongs in metadata, which is the only field that accepts arbitrary shape.

​
Idempotency

Send an optional Idempotency-Key request header to make retries safe:
A delivery carrying a key already seen for your account returns 200 {"status": "duplicate"} and creates nothing. Idempotency keys are scoped to the account, not to the key mode. A value burned with a sandbox key suppresses the same value arriving later with a live key, so do not carry test values over when switching modes.
Without an Idempotency-Key, the endpoint does not detect repeats. Every delivery is accepted and returns {"status": "ok"}, including one that is byte-identical to the delivery before it. Send the header on any request your client might retry — it is the only way to get a repeat reported back to you rather than silently accepted.
Generate the key from something stable in your own system, such as the submission ID of the form that produced the lead. Reusing that value on every retry of the same submission is what makes the retry safe.

​
Contact matching

Two things deduplicate, at different layers, and they are worth keeping apart. The Idempotency-Key deduplicates deliveries. A repeat is rejected before any work happens and reported to you as {"status": "duplicate"}. Contact matching deduplicates people. After a delivery is accepted, DeltaLead matches it against your existing contacts on email or phone. A match resolves onto the existing lead and enriches it rather than creating a second one — so a delivery carrying only a phone can attach to a lead created earlier from an email, and the contact ends up holding both. The practical consequence is that a delivery which matches an existing contact still returns {"status": "ok"}, not duplicate. The 200 tells you the delivery was accepted; it never tells you whether a new lead was created.
Matching is on email or phone, not both. Two genuinely different people who share a phone number — a household, or a dealership switchboard — resolve to the same lead. Send the most specific contact details you have.

​
Limits

Rate limits apply per route.

​
Responses

A successful delivery returns a status:
200 OK
A failure returns an error envelope, where detail identifies the cause:
401 Unauthorized
The route accepts POST only. Any other method, or any other path on this host, returns 404 {"message": "Not Found"} from the gateway before the webhook handler runs. A 200 confirms that DeltaLead has accepted the delivery, not that the lead exists. The lead is created asynchronously a few seconds later.
Retry on 500 enqueue_failed — the delivery was valid and the failure is on our side. Do not retry any 4xx; the request will fail again unchanged. Always send an Idempotency-Key on a request you might retry, since retries are only deduplicated when you do.

​
Examples

Sandbox — the minimum valid request:
cURL
Live — the same request with every field:
cURL
Live, with an idempotency key — safe to retry:
cURL