Recevoir les événements Formaloo avec des webhooks
Les webhooks de Formaloo vous permettent de recevoir automatiquement les événements importants de vos formulaires dès qu’ils se produisent. Par exemple, au lieu de vérifier régulièrement si votre formulaire a reçu de nouvelles soumissions, les webhooks vous envoient une notification (accompagnée des données correspondantes) dès que votre formulaire reçoit une nouvelle soumission.
Chaque formulaire peut avoir plusieurs webhooks, chacun envoyant les notifications et les données vers une URL spécifique. Chaque webhook peut gérer plusieurs événements prédéfinis : lorsqu’un webhook est ajouté à un formulaire, il peut être appelé pour plusieurs types d’événements liés à ce formulaire.
💡 Informations complémentaires :
Webhooks
Chaque webhook doit présenter les caractéristiques suivantes :
Une adresse URL qui accepte les données POST.
La réponse doit renvoyer un code de statut
HTTP 200, avec un corps vide.Vous pouvez éventuellement définir un secret sur votre webhook, qui sera envoyé dans l’en-tête de la requête avec la clé
X-Formaloo-Token, afin de vous assurer que le webhook est bien appelé par Formaloo.
Lorsqu’un événement de webhook est déclenché, nous envoyons une requête POST à l’adresse du webhook avec les caractéristiques suivantes :
Le corps contient les données de l’événement (par exemple, les données du formulaire soumis). Nous y reviendrons plus en détail dans la section Événements.
L’en-tête contient le
X-Formaloo-Tokensi vous avez défini lesecretsur votre webhook. Le corps de la requête contient les données liées à l’événement.
Chaque requête de webhook n’est considérée comme réussie que lorsqu’elle reçoit une réponse avec un corps vide et un code de statut HTTP 200. En cas d’échec de l’envoi, nous réessayons plusieurs fois, avec quelques secondes d’intervalle à chaque fois. Si toutes les tentatives échouent après un nombre défini d’essais, l’événement est considéré comme ayant échoué.
Ajouter des webhooks à vos formulaires
Pour ajouter des webhooks à votre formulaire, suivez ces étapes dans votre tableau de bord Formaloo :
Depuis votre profil en haut à droite, accédez à Apps & Integrations,
Accédez à Webhooks pour ouvrir le menu Add new integration,
Saisissez les informations du webhook et activez les événements souhaités,
Utilisez la liste des webhooks pour gérer les webhooks existants.
Événements
Chaque événement représente une action du système dont vous souhaitez être informé dès qu’elle se produit, tout en recevant ses données. Par exemple, vous souhaitez appeler une fonction de votre système chaque fois qu’un formulaire est soumis, sans consulter la liste des soumissions via l’API en attendant une mise à jour.
Actuellement, nos webhooks prennent en charge trois événements liés aux formulaires :
➔ Événement de soumission de formulaire
Ce webhook est appelé chaque fois que le formulaire reçoit une nouvelle soumission, que ce soit de la part de l’utilisateur final ou de l’administrateur du formulaire. Cet événement est déclenché juste après la soumission du formulaire et envoie à l’URL du webhook les données soumises, les données de calcul et quelques données de base (par exemple, l’heure de soumission). Notez que cet événement n’est pas déclenché lorsqu’une ligne est modifiée par l’administrateur ou que son statut de paiement est mis à jour.
ℹ️ Pour les formulaires de paiement, utilisez l’événement de paiement de formulaire.
Exemple de données
Exemple de données envoyées au webhook pour un formulaire qui recueille le nom complet et le numéro de téléphone de l’utilisateur :
{ "event_type": "form_submit", "event_id": "xEJsGn", "data": { "field_QkcERTTt": "+1677673423", "field_tClRSgaU": "Joh Doe" }, "rendered_data": [ { "slug": "field_tClRSgaU", "type": "short_text", "title": "Full Name", "value": "Joh Doe", "json_key": null, "position": 1, "raw_value": "Joh Doe", "admin_only": false, "json_value": null, "max_length": 255 }, { "slug": "field_QkcERTTt", "type": "short_text", "title": "Phone Number", "value": "+1677673423", "json_key": null, "position": 2, "max_value": null, "min_value": null, "raw_value": "+1677673423", "admin_only": false, "json_value": null } ], "readable_data": { "Full Name": "Joh Doe", "Phone Number": "+1677673423" }, "created_at": "2020-11-19T14:57:43.796281+01:00", "updated_at": "2020-11-19T14:57:43.796281+01:00", "submit_code": "UZF9XpVgY4sr5zmF", "slug": "ZNtjCuScAjt349Rf" }
Remarque : la clé data contient les données brutes, sans métadonnées. Elle est utile si vous utilisez l’API Formaloo pour obtenir les données complètes des champs et interpréter vous-même les données. Sinon, les données rendues contiennent tout ce que vous devez savoir sur les données soumises.
➔ Événement de mise à jour de ligne
Ce webhook est appelé chaque fois qu’une ligne du formulaire est modifiée. Cet événement est déclenché juste après la modification de la ligne et envoie les données complètes de la ligne à l’URL du webhook.
Exemple de données
Le formulaire d’exemple recueille le nom complet et le numéro de téléphone de l’utilisateur
{ "event_type": "row_update", "event_id": "xEJsGn", "data": { "field_QkcERTTt": "+1677673423", "field_tClRSgaU": "Joh Doe" }, "rendered_data": [ { "slug": "field_tClRSgaU", "type": "short_text", "title": "Full Name", "value": "Joh Doe", "json_key": null, "position": 1, "raw_value": "Joh Doe", "admin_only": false, "json_value": null, "max_length": 255 }, { "slug": "field_QkcERTTt", "type": "short_text", "title": "Phone Number", "value": "+1677673423", "json_key": null, "position": 2, "max_value": null, "min_value": null, "raw_value": "+1677673423", "admin_only": false, "json_value": null } ], "readable_data": { "Full Name": "Joh Doe", "Phone Number": "+1677673423" }, "created_at": "2020-11-19T14:57:43.796281+01:00", "updated_at": "2020-11-13T10:23:43.234323+01:00", "submit_code": "UZF9XpVgY4sr5zmF", "slug": "ZNtjCuScAjt349Rf" }
➔ Événement de paiement de formulaire
Cet événement est déclenché lorsqu’une transaction de paiement est finalisée, c’est-à-dire lorsque l’utilisateur a soumis un formulaire de paiement et mené à bien le processus de paiement. Cet événement envoie toutes les données soumises (comme l’événement de soumission de formulaire), accompagnées des données de paiement, comme le montant, le code de commande, etc.
Si vous activez à la fois l’événement de soumission de formulaire et l’événement de paiement de formulaire sur un même formulaire, vous recevrez deux événements pour un paiement réussi : l’un juste après la création de la soumission, l’autre après la finalisation du paiement. Si vous procédez ainsi pour une raison quelconque, veillez à traiter correctement les données pour éviter les doublons (par exemple, mettez à jour l’enregistrement existant à la réception de l’événement de paiement au lieu de créer un nouvel enregistrement).
Exemple de données
Supposons que les utilisateurs choisissent leur repas dans une liste et le paient. Les données de paiement sont ajoutées à la fin de la liste rendered_data.
{ "event_type": "row_payment", "event_id": "xEJsGn", "data": { "field_QkcERTTt": "+1677673423", "field_cfUkTmtq": "choice_kQqwcAXH", "field_tClRSgaU": "Joh Doe" }, "rendered_data": [ { "slug": "field_tClRSgaU", "type": "short_text", "title": "Full Name", "value": "Joh Doe", "json_key": null, "position": 1, "raw_value": "Joh Doe", "admin_only": false, "json_value": null, "max_length": 255 }, { "slug": "field_QkcERTTt", "type": "short_text", "title": "Phone Number", "value": "+1677673423", "json_key": null, "position": 2, "max_value": null, "min_value": null, "raw_value": "+1677673423", "admin_only": false, "json_value": null }, { "slug": "field_cfUkTmtq", "type": "dropdown", "title": "Select the food you want to buy", "value": "Pizza", "json_key": null, "position": 3, "raw_value": "choice_kQqwcAXH", "admin_only": false, "json_value": null, "delta_score": { "grade": 0.0, "currency": 15.0 }, "choice_items": [ { "slug": "choice_zrKaPTwY", "image": null, "title": "Pasta", "deleted": null, "json_key": null, "position": 1, "created_at": "2021-07-25T11:14:07.806553+04:30", "updated_at": "2021-07-25T11:14:07.861721+04:30" }, { "slug": "choice_mTpKFfXl", "image": null, "title": "Burger", "deleted": null, "json_key": null, "position": 2, "created_at": "2021-07-25T11:14:07.806553+04:30", "updated_at": "2021-07-25T11:14:07.861721+04:30" }, { "slug": "choice_kQqwcAXH", "image": null, "title": "Pizza", "deleted": null, "json_key": null, "position": 3, "created_at": "2021-07-25T11:14:07.806553+04:30", "updated_at": "2021-07-25T11:14:07.861721+04:30" } ] }, { "slug": "order_status", "title": "Order Status", "value": "Successful", "json_key": null, "position": -1 }, { "slug": "order_code", "title": "Order Code", "value": "4908799754916322", "json_key": null, "position": 1000 }, { "slug": "payment_amount", "title": "payment amount", "value": 15.0, "json_key": null, "position": 999 } ], "readable_data": { "Full Name": "Joh Doe", "Phone Number": "+1677673423", "Order Status": "Successful", "Order Code": "4908799754916322", "payment amount": 15.0 }, "created_at": "2020-11-19T14:57:43.796281+01:00", "updated_at": "2020-11-13T10:23:43.234323+01:00", "submit_code": "UZF9XpVgY4sr5zmF", "slug": "ZNtjCuScAjt349Rf" }
➔ Webhooks conditionnels
En plus du déclenchement des webhooks sur les événements de formulaire standard, vous pouvez activer les webhooks conditionnels. Cette option permet d’exécuter le webhook uniquement lorsque certaines conditions logiques sont remplies.
Une fois cette option activée, vous pouvez référencer le webhook dans la logique conditionnelle de votre formulaire et définir précisément quand il doit être déclenché. Par exemple, vous pouvez envoyer les données de soumission uniquement lorsqu’un champ a une valeur précise, lorsqu’un score dépasse un seuil ou lorsqu’une option particulière est sélectionnée.
Vous contrôlez ainsi mieux le moment où les systèmes externes reçoivent les données, ce qui vous permet d’éviter des appels de webhook inutiles et d’automatiser uniquement les scénarios importants.
ℹ️️ Dans tous les types de webhooks, qu’ils soient déclenchés par une nouvelle soumission, une mise à jour de ligne ou un paiement réussi, la charge utile du webhook inclut un champ appelé pdf_links, qui contient la liste des URL de tous les PDF générés pour cette soumission. Par exemple :
[
'https://link_to_pdf_1',
'https://link_to_pdf_2',
'https://link_to_pdf_3'
]
💡 Pour découvrir comment transformer vos soumissions en copies PDF téléchargeables ou créer des PDF à votre image avec votre propre design, du contenu personnalisé et les données de soumission, consultez nos guides ci-dessous :
Ajouter des webhooks aux formulaires
Chaque formulaire peut avoir plusieurs webhooks. Vous pouvez définir un webhook sur un formulaire et le gérer, par exemple afficher la liste des webhooks d’un formulaire, modifier les webhooks ou en créer un nouveau. Si vous créez plusieurs webhooks sur un même formulaire, les données correspondantes sont envoyées séparément à chacun d’eux.
➔ Créer un webhook
Vous pouvez créer un webhook sur un formulaire en envoyant une requête POST contenant les champs suivants à son point de terminaison :
Point de terminaison : https://api.formaloo.net/v1.0/forms/{FORM_SLUG}/webhooks/
Méthode : POST
Champs :
url (obligatoire) L’adresse du webhook.
secret (facultatif) Une clé secrète à envoyer dans l’en-tête des requêtes du webhook sous la forme X-Formaloo-Token.
form_submit_events (facultatif, false par défaut) Faut-il envoyer un événement de webhook lors de la soumission du formulaire ?
row_update_events (facultatif, false par défaut) Faut-il envoyer un événement de webhook lorsqu’une ligne est mise à jour ?
row_payment_events (facultatif, false par défaut) Faut-il envoyer un événement de webhook à chaque paiement réussi ? (Sans effet sur les formulaires sans paiement.)
active (facultatif, true par défaut) Le webhook est-il actuellement actif ? (Surtout utile lors de la modification, pour désactiver un webhook plutôt que de le supprimer.)
send_rendered_data (facultatif, false par défaut) Inclure ou non rendered_data dans la charge utile du webhook.
send_raw_data (facultatif, false par défaut) Inclure ou non les données brutes dans la charge utile du webhook.
Exemple
// Request https://api.formaloo.net/v1.0/forms/{FORM_SLUG}/webhooks/ (POST) { "url": "https://example.net/webhook/", "secret": "SOME_SECET_TEXT", "form_submit_events": true, "row_update_events": true, "row_payment_events": true, "send_rendered_data": true, "send_raw_data": true } // Respone { "status": 201, "errors": { "general_errors": [], "form_errors": {} }, "data": { "webhook": { "url": "https://example.net/webhook/", "secret": "SOME_SECET_TEXT", "form_submit_events": true, "row_payment_events": true, "row_update_events": true, "send_rendered_data": true, "send_raw_data": true "active": true, "created_at": "2021-09-04T16:29:10.808996+04:30", "updated_at": "2021-09-04T16:29:10.809010+04:30", "slug": "FVyTMf7o" } } }
➔ Consulter tous les webhooks d’un formulaire
Vous pouvez obtenir simplement la liste des webhooks d’un formulaire en envoyant une requête GET. Le résultat est une liste non paginée de webhooks :
Point de terminaison : https://api.formaloo.net/v1.0/forms/{FORM_SLUG}/webhooks/
Méthode : GET
Exemple
// Request https://api.formaloo.net/v1.0/forms/{FORM_SLUG}/webhooks/ (GET) // Response { "status": 200, "errors": { "general_errors": [], "form_errors": {} }, "data": { "webhooks": [ { "url": "https://example.com/webhook/", "secret": null, "form_submit_events": false, "row_update_events": true, "row_payment_events": false, "active": true, "created_at": "2021-09-04T16:17:44.360965+04:30", "updated_at": "2021-09-04T16:17:44.360982+04:30", "slug": "xyLY8zjx" }, { "url": "https://example.com/webhook/", "secret": "SOME_SECET_TEXT", "form_submit_events": true, "row_update_events": true, "row_payment_events": false, "active": true, "created_at": "2021-09-04T16:28:23.811015+04:30", "updated_at": "2021-09-04T16:28:23.811030+04:30", "slug": "AWTTuWEp" }, { "url": "https://example.net/webhook/", "secret": "SOME_SECET_TEXT", "form_submit_events": true, "row_update_events": false, "row_payment_events": true, "active": true, "created_at": "2021-09-04T16:29:10.808996+04:30", "updated_at": "2021-09-04T16:29:10.809010+04:30", "slug": "FVyTMf7o" } ] } }
➔ Obtenir un objet webhook
Vous pouvez obtenir un objet webhook à l’aide de son slug, bien que toutes ses données figurent également dans la liste des webhooks.
Point de terminaison : https://api.formaloo.net/v1.0/forms/{FORM_SLUG}/webhooks/{WEBHOOK_SLUG}/
Méthode : GET
Exemple
// Request https://api.formaloo.net/v1.0/forms/{FORM_SLUG}/webhooks/{WEBHOOK_SLUG}/ (GET) // Response { "status": 200, "errors": { "general_errors": [], "form_errors": {} }, "data": { "webhook": { "url": "https://example.net/webhook/", "secret": "SOME_SECET_TEXT", "form_submit_events": true, "row_update_events": true, "row_payment_events": true, "active": true, "created_at": "2021-09-04T16:37:26.920125+04:30", "updated_at": "2021-09-04T16:37:26.920141+04:30", "slug": "FW1Otww5" } } }