WP Manifestindependent plugin directory
manifest / forms / wordpress-lead-capture

Lead Capture & CRM Sync

WordPress plugin: lead forms that keep spam out without losing real enquiries, and deliver every lead to HubSpot, Mailchimp or a webhook exactly once. Tested on WordPress 6.5 to 7.1.

★ 0stars

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/coderock-izzy/wordpress-lead-capture/archive/refs/heads/main.zip
No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.

Lead Capture & CRM Sync for WordPress

A WordPress plugin for the contact form on a small-business site. It keeps spam out without losing real enquiries, and delivers every lead to the CRM exactly once, even when the CRM is down.

Most contact forms fail a business in one of two quiet ways. A strict spam filter throws away a real customer (their password manager filled the form too fast, or they pasted a link to photos), and nobody ever knows. Or the form "sends" a lead to HubSpot or Zapier at the moment the CRM is having an outage, and that lead is gone. This plugin is built so that neither can happen silently.

Leads screen: delivery status per CRM, a pitch held for review, blocked spam and a failed delivery with a retry button

Results

Measured by php eval/run.php --gate on a seeded synthetic corpus (1,200 real enquiries and 800 spam submissions, plus a second, held-out set written with different pitch wording and never used to tune the rules), and on 1,000 leads delivered to a simulated CRM with a 2-hour outage, a network partition, server errors, rate limits, lost responses and invalid records.

Real leads lost Spam reaching the CRM (tuning / held-out)
Honeypot only 5 of 2,400 63% / 65%
Strict rules (5-second minimum, no links, JavaScript required) 760 of 2,400 29% / 27%
Keyword blocklist 141 of 2,400 10% / 47%
This plugin (layered scoring) 0 of 2,400 7.9% / 39.6%
Delivery strategy Delivered exactly once Lost Duplicated Invalid records shown to the admin
Send once from the request 880 / 985 105 0 0 / 15
Retry three times immediately 906 / 985 52 27 0 / 15
Durable queue (this plugin) 985 / 985 0 0 15 / 15

Two overlapping cron runs sent 0 leads twice with the worker lease, and 200 of 200 without it.

What the numbers say, plainly: the behavioural signals (honeypot, signed timing token, flood detection) catch every crude bot and generalise to new spam. The wording rules do not: on pitches phrased differently from the ones the rules were written against, 40% of spam still reaches the CRM. That is the limit of any self-contained filter, and the reason the plugin exposes a hook for a reputation service such as Akismet or Cloudflare Turnstile (known limitations).

Evaluation report

What it does

For the visitor

  • An accessible form (labels, inline errors announced to screen readers, focus moved to the first problem) as a block or the [lead_capture_form] shortcode.
  • Works without JavaScript: the form posts normally and redirects back with a thank-you. With JavaScript it submits in place, and falls back to a normal post if the request fails, so a lead is never lost to a script error.
  • Explicit consent checkbox (the text they agreed to is stored with the lead) and an optional marketing opt-in.
The lead form with inline validation errors

Spam protection: score, don't guess

  • Independent signals: a honeypot, a signed render-time token (HMAC, works on cached pages), submission speed, links and link markup, sales phrases, high-risk words, unsolicited-offer detection, disposable email domains, random-looking names, bursts from one address (stored only as a salted hash, for an hour).
  • No single signal rejects a lead. Two independent bot signals reject; borderline submissions are held for review instead of discarded. Rejected bots see the normal thank-you, so they learn nothing.
  • Filters for your own vocabulary (lccrm_risky_phrases, lccrm_disposable_domains) and for a second opinion (lccrm_spam_verdict).

Delivery to the CRM

  • HubSpot (contact upsert by email), Mailchimp (PUT by email hash, new members pending so they confirm, and only for people who opted in), and a signed webhook for Zapier, Make, n8n or your own endpoint (Idempotency-Key header and X-Signature: sha256=HMAC(body)). Add more with the lccrm_destinations filter.
  • The lead is saved before anything is sent. Each destination gets a job with retries, exponential backoff with jitter, Retry-After honoured, a worker lease so overlapping cron runs cannot double-send, and a failed state with a one-click retry for problems a person must fix (an expired API key).
  • API secrets can live in wp-config.php (LCCRM_HUBSPOT_TOKEN, LCCRM_MAILCHIMP_API_KEY, LCCRM_WEBHOOK_SECRET); stored secrets are never echoed back into the settings page.

Privacy (GDPR / CCPA)

  • Registered with WordPress's Export / Erase Personal Data tools; erasure warns that CRM copies must be erased there too.
  • Retention: leads older than the configured number of days are deleted daily.
  • Suggested privacy-policy text under Settings → Privacy. Uninstalling removes every table and option.

For the site owner

  • A Leads screen (WP_List_Table) with delivery status per CRM, the spam score and its reasons, bulk approve and delete, and CSV export that neutralises spreadsheet formulas (CSV injection).
  • An email for every new lead with Reply-To set to the visitor.

Settings screen

How it works

Form (block / shortcode, works without JS)
   │  POST /wp-json/lccrm/v1/leads   or   admin-post.php
   ▼
Intake ── validate ──► SpamGuard (score from independent signals)
   │                      ├─ reject  → same thank-you, nothing stored, counter +1
   │                      ├─ review  → stored, not sent until approved
   ▼                      └─ accept
Lead stored (custom table, consent text, source page)
   │
   ▼
SyncQueue: one job per destination, random idempotency key
   │  WP-Cron every 5 min + one-off run seconds after a submission
   ▼
claim (lease) → send → delivered | retry with backoff | failed (shown, retryable)

The spam scoring, token, validation, destinations and queue are plain PHP with no WordPress calls, so they are unit-tested and evaluated offline; the WordPress layer (tables, REST, admin, privacy) is covered by integration tests in a real WordPress.

Design decisions are recorded in docs/adr.

Run it

docker compose up -d
bash tests/integration/run.sh          # installs WordPress, activates the plugin, runs every check
# http://127.0.0.1:8080/wp-admin  (admin / admin)

Or install it in any WordPress 6.5+ site with PHP 8.1+: copy the folder to wp-content/plugins/, activate Lead Capture & CRM Sync, add the Lead form block to a page, then set up delivery under Leads → Settings.

Tests

Layer What runs Where
Unit 35 PHPUnit tests: scoring, tokens, validation, request building, retries, leases, CSV PHP 8.1, 8.2, 8.3, 8.4
Integration 18 checks inside WordPress (REST, storage, email, privacy export and erase, retention, CSV, cron) and 9 over HTTP (token endpoint, JSON and no-JavaScript submissions, delivery to a mock CRM that fails once, signatures, uninstall) WordPress 6.5 and latest
Evaluation spam filtering on tuning and held-out sets, delivery through an outage, overlapping workers, token forgery, CSV payloads: 10 gated checks CI
Static WordPress Coding Standards 3 with PHPCompatibility (8.1+), PHPStan level 8 with WordPress stubs CI
composer install
vendor/bin/phpunit
vendor/bin/phpcs && vendor/bin/phpstan analyse
php eval/run.php --gate                 # writes eval/reports/report.{md,json,html}

Project layout

lead-capture-crm.php      plugin header and bootstrap
src/Spam/                 SpamGuard, FormToken, Submission, Verdict
src/Sync/                 SyncQueue, destinations (HubSpot, Mailchimp, webhook), job stores, transport
src/Lead/                 validation, intake pipeline, repository, schema
src/Admin/                leads list, settings, CSV export
src/Front/ src/Rest/      form renderer and no-JS handler, REST routes
src/Privacy/              exporter, eraser, retention, policy text
blocks/lead-form/         block.json and editor script (dynamic block, no build step)
eval/                     corpus, baselines, delivery simulation, report
tests/unit/ tests/integration/

Documentation

All names, emails and messages in the corpus, tests and screenshots are invented.

License

GPL-2.0-or-later, like WordPress.