Webhooks personnalisés

Comment ça fonctionne

À chaque soumission, formbase envoie un corps JSON en POST vers votre URL webhook. La requête est signée avec HMAC-SHA256, relancée en cas d’échec, et consignée dans le journal d’événements de l’intégration. Cette page couvre la configuration. La forme exacte du payload, les en-têtes et l’algorithme de signature vivent dans la référence webhook.

Ajouter un webhook

1. 1

   Ouvrir les intégrations du formulaire

   Formulaire → Paramètres → Intégrations → Webhook.

2. 2

   URL

   Saisissez l’hôte et le chemin — le préfixe https:// est fixe dans le champ. http:// n’est accepté que pour localhost pendant le développement.

3. 3

   Mapping

   Laissez-le vide pour envoyer chaque champ. Ajoutez des lignes pour n'envoyer que ces champs, sous la clé JSON de votre choix. Le mapping façonne answers et display ensemble : une clé renommée l'est dans les deux. La requête complète sous le mapping se met à jour à mesure que vous le modifiez.

4. 4

   En-têtes

   Un secret de signature commençant par whsec_ est généré automatiquement. Il ne peut pas être modifié après la création. Sur la même étape, ajoutez jusqu’à 5 en-têtes personnalisés dont votre endpoint a besoin, comme un jeton d’autorisation, et activez Envoyer la liste des champs avec chaque événement si votre récepteur ne peut pas appeler fields.list. Content-Type est défini automatiquement et ne peut pas être remplacé.

5. 5

   Finaliser

   Appuyez sur Envoyer un événement de test pour envoyer en POST un exemple de soumission synthétisé, puis appuyez sur Créer l’intégration.

Quelles URL formbase accepte

• https:// partout, ou http:// pour localhost et *.localhost pendant le développement.

• Aucun identifiant dans l’URL, et au plus 2 048 caractères.

• Aucune adresse privée ou interne. Le nom d’hôte est résolu et revérifié juste avant chaque livraison, si bien qu’un enregistrement DNS repointé vers une adresse interne après la configuration reste refusé.

Une URL refusée est un problème de configuration, pas transitoire : la livraison échoue définitivement au lieu d’être relancée.

Ce que vous recevez

Chaque requête est la même enveloppe d’événement — id, type, createdAt, apiVersion, test et data. Dans data se trouvent le formulaire, la soumission (id, e-mail du répondant, heure de soumission, lien PDF, langue), un objet answers indexé par clé de champ, et un objet display avec les mêmes clés en texte lisible. Chaque réponse apparaît une fois, dans chaque map.

Consultez la référence pour la forme complète du payload, answers et display, et comment un groupe répétable est représenté.

Pour prévisualiser le corps exact pour votre formulaire, ouvrez l’intégration et développez Exemple de payload sous le secret de signature. Il affiche votre mapping actuel avec des réponses d’exemple.

Vérifier les signatures

Chaque requête inclut un en-tête X-formbase-Signature : t=TIMESTAMP,sha256=HEX, un HMAC-SHA256 de TIMESTAMP.BODY calculé avec votre secret de signature. Le secret lui-même n’est jamais envoyé. La référence contient un extrait de vérification prêt à copier.

Événements de réponses abandonnées

Les webhooks personnalisés se déclenchent uniquement pour les soumissions complètes et les modifications — jamais pour les brouillons abandonnés. Un webhook personnalisé est le seul récepteur qui reçoit les deux : un abonnement Zapier, Make ou n8n choisit les premières soumissions ou les modifications, jamais les deux. Pour les brouillons abandonnés, utilisez un fournisseur qui dispose d’une étape Soumissions abandonnées : Google Sheets, Airtable, Notion, Slack, Discord, Linear ou GitHub Issues. Chacun a sa propre fenêtre d’inactivité et, le cas échéant, son propre modèle de message. Cette étape nécessite Pro ou Business.

Nouvelles tentatives et échecs

• Une livraison réussit sur n’importe quel 2xx.

• Jusqu’à 5 tentatives : la première est envoyée immédiatement, les suivantes attendent au moins 1, 2, 4 et 8 minutes. formbase recherche les tentatives dues toutes les 30 minutes, la dernière tentative arrive donc environ deux heures après la première. Un en-tête Retry-After sur un 429 ou 5xx est respecté quand il demande une attente plus longue.

• 429, 5xx, les délais dépassés et les échecs de connexion sont relancés. Toute autre erreur 4xx échoue immédiatement.

• Après 5 échecs consécutifs, l’intégration se met en pause automatiquement et la personne qui l’a configurée reçoit un e-mail. Corrigez l’endpoint, puis appuyez sur Reprendre.

• 401, 403 et 404 arrêtent immédiatement l’intégration avec un statut d’erreur et le même e-mail — inutile d’attendre cinq échecs.

• Les livraisons qui ont épuisé leurs 5 tentatives s’accumulent dans une bannière sur l’intégration. Réessayer tous les remet en file et réactive une intégration en pause.

Tests

Envoyer un événement de test apparaît sur l’étape Finaliser et à nouveau sur l’intégration enregistrée. Il envoie en POST un exemple de soumission synthétisé — “John Doe” pour le texte, 42 pour les nombres, john@example.com pour l’e-mail — signé et avec vos en-têtes personnalisés, exactement comme une vraie livraison. Depuis l’intégration enregistrée, il inscrit aussi une entrée de test de connexion dans le journal d’événements.

Pour le développement local, exposez votre serveur de développement avec un tunnel :

# ngrok
ngrok http 3000

# cloudflare tunnel

cloudflared tunnel --url http://localhost:3000

FAQ

Prochaines étapes