Formstep

Du JSON signé vers votre propre endpoint

Quand la destination est votre propre backend, une fonction serverless ou un outil sans intégration native, le webhook est l'intégration. Chaque soumission arrive comme un événement JSON, indexé par clé de champ, signé pour que vous puissiez prouver qu'il vient de Formstep, et renvoyé jusqu'à ce que votre endpoint réponde oui.

Mis à jour

Comment ça marche

  1. Ouvrez les Intégrations du formulaire, choisissez Webhook et saisissez l’URL. Laissez l’association vide pour envoyer tous les champs, ou ajoutez des lignes pour n’en envoyer que certains, sous les clés JSON de votre choix. Voir un exemple de requête montre le corps changer pendant que vous modifiez.
  2. Copiez le secret de signature, qui commence par whsec_ et ne s’affiche qu’une fois. Ajoutez jusqu’à cinq en-têtes personnalisés, comme un jeton d’autorisation.
  3. Cliquez sur Activer Webhook, puis sur Envoyer un événement de test : un POST signé avec des réponses d’exemple et vos en-têtes, consigné dans le journal des événements comme un vrai envoi.

Voir le guide complet

Ce qui arrive

Une seule enveloppe pour tout ce que Formstep envoie : id, type, createdAt, apiVersion, test et data. Sous data : le formulaire, la soumission avec son identifiant, l’e-mail du répondant, l’heure, la langue et le lien du PDF, un objet answers pour le code, indexé par clé de champ, et un objet display avec les mêmes clés en texte lisible. Une réponse à choix est sa clé d’option dans answers et son libellé dans display ; un fichier est une liste avec les URL de téléchargement dans l’un et les noms de fichier dans l’autre. Une soumission qui répond à une demande ajoute un bloc request avec votre identifiant externe et vos métadonnées.

X-Formstep-Signature: t=TIMESTAMP,sha256=HEX

Un formulaire peut avoir plusieurs webhooks ; chacun se déclenche à chaque soumission et à chaque modification ultérieure, distinguées par type. Activez Envoyer la liste des champs avec chaque événement si votre récepteur ne peut pas appeler fields.list lui-même.

Nouvelles tentatives

Tout 2xx est un succès. Formstep essaie jusqu’à cinq fois : tout de suite, puis après au moins 1, 2, 4 et 8 minutes, de sorte que la dernière tentative a lieu environ deux heures après la première. Les 429, 5xx, délais dépassés et échecs de connexion sont retentés, et un Retry-After plus long est respecté. Les 401, 403 et 404 arrêtent aussitôt l’intégration et envoient un e-mail à la personne qui l’a configurée. Les envois qui ont épuisé les cinq tentatives apparaissent dans un bandeau sur l’intégration ; Réessayer tous les renvoie et réactive une intégration en pause.

Pour le développement local, exposez votre serveur de développement avec ngrok ou un tunnel Cloudflare et pointez le webhook dessus. Pour les réponses inachevées à un lien public, créez un abonnement submission_abandoned avec l’API REST ; le webhook que vous ajoutez ici ne se déclenche jamais pour elles.

Un outil de workflow avec un trigger webhook, comme Make ou Pipedream, peut aussi les recevoir. Si le récepteur est un workflow qui attend une personne précise, il vous faut plutôt le callback d’une demande qu’un webhook : il se déclenche une seule fois, pour cette demande, avec son résultat.

Questions sur Formstep pour Webhooks

Autre chose en tête ? La documentation couvre chaque paramètre, et nous répondons aux e-mails.

Lire la documentation

Un webhook appartient au formulaire et se déclenche à chaque soumission, qu'elle vienne de liens de partage ou de demandes. Un callback appartient à une seule demande : c'est l'URL que vous passez comme callbackUrl à sa création, appelée une fois quand la demande se termine. Les deux portent la même enveloppe d'événement.

Chaque requête a un en-tête X-Formstep-Signature de la forme t=TIMESTAMP,sha256=HEX : un HMAC-SHA256 de TIMESTAMP, d'un point et du corps brut, avec votre secret de signature. Hachez le corps exactement tel qu'il est arrivé. La référence des webhooks contient un extrait à copier.

Le propriétaire de l'espace de travail peut l'afficher dans le tableau de bord ; les autres membres voient le reste du webhook. Il ne peut pas être régénéré : pour un nouveau secret, supprimez le webhook et créez-en un nouveau.

HTTPS sur une adresse publique, jusqu'à 2 048 caractères, sans identifiants dans l'URL. Un simple http:// fonctionne pour localhost pendant le développement. Formstep revérifie le nom d'hôte avant chaque envoi : un enregistrement DNS redirigé plus tard vers une adresse interne est donc toujours refusé.

Collectez des informations auprès de qui vous voulez.

Publiez un exemple de formulaire, répondez-y comme le ferait votre destinataire et regardez les réponses revenir. Aucun compte requis.

Lire la documentation