n8n Lead Intake: Seven Executable Contract Checks

A lead workflow needs a clear definition of success for repeat submissions, conflicting data and failed writes. I built a runnable contract-test harness that makes those outcomes visible before connecting a destination CRM.

How it works Actual n8n 2.47.3 sends seven sequential HTTP requests to a local Python/SQLite mock CRM. Each HTTP Request node is followed by a JavaScript assertion that checks the status, outcome and record counts. The Python/SQLite fixture owns contact deduplication, source-event tracking and transactional writes.

The seven checks

First delivery creates one lead, one source event and one review-task record.

Exact replay leaves all three counts unchanged.

A second source event with the same normalized email links to the existing lead.

Changed details under the original event key return HTTP 422 and preserve the records.

Invalid email returns HTTP 422.

An injected exception before commit returns HTTP 503 and rolls back the writes.

A separately scripted subsequent delivery succeeds.

Observed result The workflow completed twice, with all seven n8n assertions passing in each run. Each run ended with 2 leads, 3 source events and 2 review-task records. A separate Python database assertion checked those final counts after n8n exited.

Synthetic retry test: recovery and terminal failure A fresh n8n 2.47.3 run on 11 November passed the original 7/7 checks and an additional seven-case workflow with actual automatic retries. The added suite also checks missing required fields, exact replay and changed payloads under the same event key.

Transient pre-commit failures returned 503, 503, then 200. Persistent failure returned 503 three times. The two fault-injected HTTP nodes allow three total attempts (two retries), with a fixed 250 ms wait and a 2-second HTTP timeout.

The local CRM fixture finished with 2 leads, 3 events and 2 review tasks. Exact replay added no duplicate business records. The exhausted event committed zero business records, and n8n sent one observed failure alert to the local alert sink, recorded in its JSONL log.

The fixture uses the trimmed (source, event_id) pair as its event key and trimmed, lowercased email for lead/task matching. Python/SQLite performs validation, normalization, deduplication and transactional writes; n8n performs HTTP orchestration, assertions, retries and the alert call.

For acceptance, check both the stored records and the terminal failure signal. Recovery should create only the intended records, while exhaustion should leave an observable event for review. The additional exportable workflow and sanitized evidence are included in the prepared verification bundle.

What makes this useful The test harness checks the orchestration and the destination behavior separately. A successful HTTP response alone is not enough: the expected data state is part of the acceptance test. The demonstration uses fictional contacts and a loopback endpoint; the results describe this sequential local setup.

For a real CRM integration, I would first agree the event key, contact-matching policy and expected record counts, then verify those rules against the destination API. The same cases can become regression checks after field mappings or workflow steps change.

Reproducible package The prepared bundle includes the pinned n8n dependency, importable workflow, mock API, fixture logic, run script and sanitized evidence for both runs.

Have a lead workflow that creates duplicates or loses source history? Send a redacted example of the input and the expected result so we can define a focused acceptance test.