Skip to main content
ALTCHA®

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

ThreatWhat stops it
Bots that post straight to your form endpointNo valid widget payload: your backend rejects the request before it reads the form.
Headless browsers that solve the proof-of-workRate 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 dropsThe text rules, the phishing list, similarity with your own spam examples and, optionally, the AI decider.
Injection probes in form fieldsThe five injection rules, which make the classification BAD.
The same message sent from many IPsCAMPAIGN, without any training data.
Tampered or replayed submissionsfieldsHash binds the classification to the submitted values, and Sentinel accepts each payload once.

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:

PresetKindWhy
RecommendedBaseThreat blocking, a rate limit of 50/10m per device, header-entropy limit, and escalation to a code challenge for risky or penalized clients.
Form fieldsAdd-onMakes the widget send the form's fields to POST /v2/verify, so the signed classification includes the email, text, injection and similarity rules.
Allowed originsAdd-on, optionalKeeps 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_PROVIDER and PRIVACY_RELAY.
  • Every form that should be classified differently needs its own public key in its own group, or conditions on the set rule. 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 default

See Similarity & training data and [similarity].

API keys

KeyGroupUsed by
publicThe contact-form group above. Set Request logging to Verification.The widget
restrictedA 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_…&params.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, set serverVerificationFieldNames. See Which fields the widget sends.
  • The email field. Sentinel checks the domain of the email address (MX, DISPOSABLE, FREE_PROVIDER, …): the field named email, or else a value shaped like an address. Widgets before 3.7.0 don't send type="email" inputs; with those, use type="text" inputmode="email", or classify the address from your backend with POST /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's classifier.fields rule overrides the challenge URL's fields parameter.

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);
  • verified alone 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 has fields and fieldsHash. Requiring them stops a client from verifying an empty form and then submitting different text.
  • Pick your own threshold. classification is GOOD below a score of 1, NEUTRAL below 2 and BAD from 2. Use data.score for a finer cut. See Decide from the classification.
  • Replays. POST /v2/verify/signature accepts each payload once and answers PAYLOAD_ALREADY_USED after 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/verify signs, so it's safe to apply live. See Monitor mode.
  • Find false positives. With request logging on, each verification stores its triggeredRules. The triggeredRules breakdown of POST /v2/request-logs/_stats shows which rules fire most for the form's key. A rule that fires on normal messages, such as CURRENCY on a quote form that mentions budgets, goes into classifier.disableRules in the group's contact-classifier rule. 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 protectionLevel breakdown 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_failures alert fires when an account's failed verifications rise well above their baseline. See Alerts.

Start typing to search...

↑ ↓ Navigate ↵ Select