Protecting contact & lead forms
Contact, quote-request, demo-request and newsletter forms are the most common target for spam bots and for low-cost human spam. This page sets up the widget so that Sentinel classifies the form's fields when it verifies the solution, and shows the backend code that accepts, flags or rejects each submission based on the signed result.
Prerequisites: a running Sentinel with an active license, and an admin user who can edit security groups and API keys in the account. See Get started.
What you're defending against
| Threat | What stops it |
|---|---|
| Bots that post straight to your form endpoint | No valid widget payload: your backend rejects the request before it reads the form. |
| Headless browsers that solve the proof-of-work | Rate limits and header-entropy limits per device, plus a code challenge and a harder proof-of-work for risky clients (the Recommended preset). |
| Spam written by people or scripts: SEO offers, crypto and pharma pitches, link drops | The text rules, the phishing list, similarity with your own spam examples and, optionally, the AI decider. |
| Injection probes in form fields | The five injection rules, which make the classification BAD. |
| The same message sent from many IPs | CAMPAIGN, without any training data. |
| Tampered or replayed submissions | fieldsHash binds the classification to the submitted values, and Sentinel accepts each payload once. |
Recommended configuration
Security group for the form
Create a public security group for your contact forms and apply these presets from Security groups → Create security group → Templates:
| Preset | Kind | Why |
|---|---|---|
| Recommended | Base | Threat blocking, a rate limit of 50/10m per device, header-entropy limit, and escalation to a code challenge for risky or penalized clients. |
| Form fields | Add-on | Makes the widget send the form's fields to POST /v2/verify, so the signed classification includes the email, text, injection and similarity rules. |
| Allowed origins | Add-on, optional | Keeps the key off other websites. |
Then add your own rule after the presets, to choose the training groups that similarity compares with and, optionally, to ask the AI decider whether a message fits the form:
{
"name": "contact-classifier",
"action": "set",
"set": [
{ "field": "classifier.similarityGroups", "value": "contact_spam" },
{ "field": "classifier.ai", "value": "true" },
{ "field": "classifier.aiPurpose", "value": "Contact form of a B2B software company: questions about products, pricing, demos and support" }
]
}The group's rules then run in this order:
preset:origins:allow
preset:forms:classifier
preset:recommended:threats
preset:recommended:base
preset:recommended:elevated
preset:recommended:high
contact-classifier- Leave out the two
classifier.ai*entries if the server has no[classifier.ai]provider. See AI decider. - For a form where most visitors use free email providers, such as a newsletter sign-up, apply Form fields (consumer sign-ups) instead of Form fields. It also disables
FREE_PROVIDERandPRIVACY_RELAY. - Every form that should be classified differently needs its own
publickey in its own group, or conditions on thesetrule. See Classify each form differently.
Server configuration
The text, injection and CAMPAIGN rules need no configuration. For similarity that catches reworded spam, choose an embedding model, and let Sentinel queue texts that the text rules find spammy so you can turn them into training data:
[similarity]
provider = "local" # ONNX model, ~135 MB download at startup
[similarity.suggestions]
enabled = true # stores message text for review; off by defaultSee Similarity & training data and [similarity].
API keys
| Key | Group | Used by |
|---|---|---|
public | The contact-form group above. Set Request logging to Verification. | The widget |
restricted | A backend group with the Backend API (allowed IPs) preset. See Backend & API protection. | Your backend, for POST /v2/verify/signature and POST /v2/training-data/_feedback |
See Managing API keys.
Integration steps
Step 1 — Add the widget to the form
Install widget 3.7.0 or later in your page as described in Widget integration. Then point it at Sentinel with the public key, and tag the challenge with a custom parameter so your backend can check that the payload was made for this form:
<form action="/contact" method="post">
<input type="text" name="name" autocomplete="name" required />
<input type="email" name="email" autocomplete="email" required />
<input type="text" name="company" autocomplete="organization" />
<textarea name="message" required></textarea>
<input type="text" name="orderNumber" data-no-spamfilter />
<altcha-widget
challenge="https://sentinel.example.com/v2/challenge?apiKey=key_…¶ms.formId=contact"
></altcha-widget>
<button type="submit">Send</button>
</form>- Which fields are sent. The widget sends the non-empty values of text inputs, email inputs and textareas, except those marked
data-no-spamfilter. Password, phone and other inputs aren't sent. To pick fields by name instead, setserverVerificationFieldNames. See Which fields the widget sends. - The email field. Sentinel checks the domain of the email address (
MX,DISPOSABLE,FREE_PROVIDER, …): the field namedemail, or else a value shaped like an address. Widgets before 3.7.0 don't sendtype="email"inputs; with those, usetype="text" inputmode="email", or classify the address from your backend withPOST /v2/classifier. See Classifier. - Fields that aren't prose. Mark order numbers, phone numbers and similar fields with
data-no-spamfilter, so their values don't feed the text rules. - No
fields=1. The Form fields preset'sclassifier.fieldsrule overrides the challenge URL'sfieldsparameter.
See Widget integration and Custom parameters & fields.
Step 2 — Verify and decide on your backend
Verify the payload with POST /v2/verify/signature before you read the form. This Express handler uses altcha-lib 2.9.0 or later, which returns verificationData with flat keys such as params.formId:
import { verifyFieldsHash, verifyServer } from 'altcha-lib';
import express from 'express';
const app = express();
app.use(express.urlencoded({ extended: false }));
app.post('/contact', async (req, res) => {
const result = await verifyServer({
payload: req.body.altcha,
url: 'https://sentinel.example.com/v2/verify/signature',
apiKey: { id: 'key_…', secret: process.env.SENTINEL_API_KEY_SECRET! }, // restricted key
});
const data = result.verified ? result.verificationData : null;
if (
!data ||
data['params.formId'] !== 'contact' ||
!data.fields ||
!(await verifyFieldsHash({ formData: req.body, fields: data.fields, fieldsHash: String(data.fieldsHash) }))
) {
res.status(400).send('Verification failed. Please try again.');
return;
}
const reasons = data.reasons ?? [];
if (data.classification === 'BAD') {
// Spam, injection, a phishing link or a strong similarity match. Keep a record if you
// want to review rejections, but don't deliver the message.
res.status(422).send('Your message could not be sent.');
return;
}
const review = data.classification === 'NEUTRAL' || reasons.includes('CAMPAIGN');
await saveMessage(req.body, { review, score: data.score, reasons }); // your code
res.send('Thank you! We will get back to you soon.');
});
app.listen(8080);verifiedalone isn't enough. It means the proof-of-work and any code challenge passed. Spam written by a person verifies too; the classification is what tells it apart.- Require
fields. With the Form fields preset, the widget sends the form's fields, so a payload from your form hasfieldsandfieldsHash. Requiring them stops a client from verifying an empty form and then submitting different text. - Pick your own threshold.
classificationisGOODbelow a score of 1,NEUTRALbelow 2 andBADfrom 2. Usedata.scorefor a finer cut. See Decide from the classification. - Replays.
POST /v2/verify/signatureaccepts each payload once and answersPAYLOAD_ALREADY_USEDafter that, so a resubmitted form fails verification.
Your backend sends any notification emails or CRM updates; Sentinel only classifies.
Step 3 — Feed spam back into training data
When someone on your team marks a delivered message as spam, or restores a rejected one, send the text to POST /v2/training-data/_feedback with the backend key. The next reworded copy then matches the contact_spam group:
curl https://sentinel.example.com/v2/training-data/_feedback \
-u 'key_…:sec_…' \
-H 'Content-Type: application/json' \
-d '{"group": "contact_spam", "label": "positive", "text": "We offer guaranteed first-page Google rankings for your website. Reply for a free audit and pricing."}'{ "data": { "duplicate": false, "id": "trd_…" } }Use "label": "negative" for a legitimate message that was flagged. A match on a positive sample with weight 1 (the feedback default) makes the classification BAD. Samples are up to 4000 characters. See Feedback from your application.
Monitoring & tuning
- Start in monitor mode. Apply the presets with Apply in monitor mode checked, watch the group's Activity tab for a few days, then turn them on. Form fields changes only what
/v2/verifysigns, so it's safe to apply live. See Monitor mode. - Find false positives. With request logging on, each verification stores its
triggeredRules. ThetriggeredRulesbreakdown ofPOST /v2/request-logs/_statsshows which rules fire most for the form's key. A rule that fires on normal messages, such asCURRENCYon a quote form that mentions budgets, goes intoclassifier.disableRulesin the group'scontact-classifierrule. See Request logs & analytics. - Review suggestions. Under Training Data → Suggestions, accept texts that the text rules caught into
contact_spam, so their rewordings are caught too. See Training suggestions. - Watch the friction. The
protectionLevelbreakdown shows how many visitors got a code challenge. If too many legitimate visitors do, switch the base preset to Recommended without code challenge. - Alert on spikes. The
verification_failuresalert fires when an account's failed verifications rise well above their baseline. See Alerts.