Périmètre sûr : Ce guide s'applique exclusivement à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni l'évasion de dispositifs anti-bot que vous ne contrôlez pas.
Webflow Logic ne sait pas résoudre un CAPTCHA par lui-même : dès qu'un de vos flux rencontre un reCAPTCHA ou un Cloudflare Turnstile, cette étape doit être déléguée à un service externe qui renvoie un token valide. CaptchaAI joue ce rôle via une seule API HTTPS, quel que soit le type de défi. Ce guide s'adresse aux agences et aux intégrateurs : l'objectif n'est pas de faire tourner le flux une fois en démonstration, mais de tenir en production, sous les runbooks d'une autre équipe.
Pourquoi déléguer la résolution à un service externe
Un flux Webflow Logic enchaîne conditions, appels HTTP et mises à jour de données, mais il n'exécute pas de navigateur et ne franchit pas un défi anti-bot. La résolution doit donc vivre dans un composant que vous contrôlez — fonction serverless, worker ou route d'API maison — qui appelle CaptchaAI, attend le token, puis le réinjecte dans la requête protégée.
CaptchaAI expose une API unique pour reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, ainsi que les CAPTCHA image (OCR) et en grille. Vous gardez le même contrat d'appel même si le type de défi change sur la page cible — d'où une intégration facile à maintenir après la livraison.
Architecture cible
Votre composant interne appelle CaptchaAI en HTTPS pour récupérer un token, puis l'injecte dans le formulaire ou la route d'API qui poursuit l'action Webflow. Tracez chaque étape avec un identifiant de corrélation propagé de bout en bout : une régression devient immédiatement visible et un incident, rejouable.
Configuration des secrets
La clé API CaptchaAI ne vit jamais dans le code source ni dans un champ Webflow. Stockez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret CI, et montez-la en variable d'environnement au runtime.
Côté RGPD, limitez les données personnelles qui transitent par ce composant : un flux de résolution de CAPTCHA n'a pas besoin du contenu des formulaires, seulement des métadonnées techniques de l'appel (type de défi, URL, durée, code retour).
Exemple de code
Voici un appel côté serveur qui crée une tâche Turnstile et renvoie son identifiant. La logique reste la même pour les autres types : vous changez le type de tâche, pas le contrat d'appel.
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Du token à la soumission, sans rejet
Une fois l'identifiant de tâche obtenu, interrogez le résultat jusqu'à recevoir le token, puis réinjectez-le dans la même session que celle qui a déclenché le défi. Deux règles écartent la majorité des rejets :
- Même session, même contexte. Le token doit repartir avec le même client HTTP et le même cookie jar que la requête d'origine — une session dépareillée est la première cause de refus après résolution.
- Interrogation mesurée. Attendez quelques secondes avant la première lecture, puis interrogez à intervalle régulier avec un plafond ferme par tâche.
Observabilité et mesure de la réussite
Instrumentez chaque appel CAPTCHA : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Séparez les journaux par environnement et corrélez-les à votre traçage distribué (par exemple OpenTelemetry) pour rejouer un scénario complet à partir d'un identifiant unique — le temps de diagnostic chute nettement en cas d'incident.
La réussite d'une tâche et celle du workflow sont deux métriques distinctes : un token obtenu ne garantit pas que l'étape en aval l'accepte. Câblez ces indicateurs dans le tableau de bord de l'application cliente et alertez sur l'écart :
- Latence du premier token (médiane et P95) — révèle si l'intégration attend des retries.
- Taux de réussite du solveur par type de CAPTCHA — confirme que vos paramètres correspondent au défi réel.
- Taux d'acceptation en aval — combien de tokens sont réellement validés dans la même session.
- Coût par résolution acceptée — une dérive signale des boucles de mauvais paramètres.
Fixez vos propres objectifs (95 % de réussite par famille, par exemple) et traitez tout écart durable comme une régression.
Liste de contrôle
- Le périmètre est strictement limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est stockée dans un coffre ou un secret CI, jamais dans le code source ni dans Webflow.
- Les durées d'appel et les codes retour sont tracés pour chaque exécution.
- Une stratégie de retry idempotent et borné est en place pour les erreurs transitoires.
- Les tests sont rejouables et reproductibles depuis votre intégration continue.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec des espaces parasites ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la en secret CI. |
ERROR_ZERO_BALANCE |
Solde sous le minimum par tâche. | Rechargez avant de réessayer et ajoutez une alerte de solde. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre requis manquant ou mal formé. | Revalidez l'URL de page et le sitekey face au HTML réel de la cible. |
| Token refusé après résolution | Token appliqué dans une session différente de celle du défi. | Gardez la résolution et la soumission dans le même contexte HTTP. |
FAQ
Webflow Logic peut-il résoudre un CAPTCHA sans service externe ?
Non. Webflow Logic orchestre des conditions et des appels HTTP, mais il n'exécute pas de navigateur capable de franchir un défi anti-bot. Il faut un composant que vous contrôlez, qui appelle une API comme CaptchaAI, récupère le token et le réinjecte dans la requête protégée.
Où stocker la clé API CaptchaAI dans un projet Webflow ?
Dans un coffre (Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret CI, jamais dans un champ Webflow ni en clair dans le code. Montez-la en variable d'environnement au runtime, côté serveur uniquement.
Ce guide couvre-t-il l'automatisation de sites tiers ?
Non. Tous les exemples portent sur vos propres applications ou sur des environnements de test autorisés par écrit. Si votre projet implique une source externe, validez d'abord les conditions d'utilisation et la base juridique avant toute automatisation.
Le coût augmente-t-il fortement avec le volume ?
Le volume évolue linéairement avec les résolutions réussies. La facturation CaptchaAI se fait par thread simultané, avec des résolutions illimitées par thread : ce sont les boucles de mauvais paramètres et les tempêtes de retry qui font grimper la dépense, pas le volume. Le plan BASIC ($15/mois, 5 threads) suffit à la plupart des intégrations Webflow ; montez en gamme quand la concurrence réelle dépasse vos threads.
Guides connexes
- Démarrage rapide CaptchaAI
- Résolution CAPTCHA en environnements de test autorisés
- Tester l'endpoint API sur vos formulaires
- Intégration CAPTCHA dans votre CI
- Résoudre reCAPTCHA v2 via l'API
Livrez une intégration Webflow propre et reproductible, prête à tenir en production. – Créez votre compte CaptchaAI.
