Un webhook envoie automatiquement les données de réponse à un système externe dès qu’un employé envoie votre formulaire. Personne n’a ainsi besoin de les exporter, de les importer ou de les saisir à nouveau manuellement. Associé à un service d’intégration développé par votre équipe technique, un webhook peut déclencher un workflow dans un autre système. Par exemple, un formulaire de signalement d’incident, de demande adressée aux RH ou de remboursement de dépenses peut alimenter directement votre système de tickets, votre système RH ou votre système de gestion des dépenses.
Chaque webhook inclut un secret d’authentification afin que le système destinataire puisse confirmer qu’une requête provient de votre environnement Staffbase. Pour choisir entre un webhook, des notifications par e-mail et une question sur le destinataire, consultez Choisir comment acheminer les données de réponse.
Fonctionnement du webhook
Une réponse déclenche un événement webhook. Staffbase envoie l’événement sous forme de requête POST avec un corps JSON à votre point de terminaison HTTPS. La charge utile contient les données de réponse ainsi que toutes les métadonnées que vous avez choisi de recueillir à partir des champs du profil utilisateur, y compris les champs système et les champs personnalisés propres à votre organisation.
En cas d’échec de livraison, Staffbase réessaie d’envoyer la requête à votre point de terminaison.
Pour ajouter un webhook à un formulaire, consultez Utiliser les paramètres du formulaire. Après l’avoir ajouté, sélectionnez les trois points à côté du webhook pour le tester, le modifier ou le supprimer :
- Livraisons : Sélectionnez Envoyer un test pour envoyer un événement de test. L’ID de livraison et le code d’état de la réponse s’affichent. Les livraisons de test sont marquées comme Test.
- Modifier : Modifiez l’URL du webhook, ou copiez ou régénérez le secret. Après avoir régénéré un secret, conservez le secret précédent et son ID de clé jusqu’à ce que les anciennes livraisons soient terminées, car les nouvelles tentatives de ces événements utilisent toujours l’ancien secret.
- Supprimer : Supprimez le webhook. Un avertissement vous demande de confirmer.
Comprendre la charge utile du webhook
La charge utile JSON contient les informations suivantes :
-
ID d’installation du formulaire : identifiant unique de votre formulaire. Pour le trouver dans Studio, ouvrez le menu des actions du formulaire et sélectionnez Copier le lien. L’ID correspond à la dernière partie de l’URL :
https://<your-environment>/content/staffbase.forms/<form-installation-ID> - Titre du formulaire : nom du formulaire. Le titre n’est pas un identifiant unique.
- ID de réponse : identifiant unique d’une réponse. Chaque réponse possède une valeur différente, même lorsqu’un même employé envoie plusieurs fois le formulaire.
- Données du répondant : informations du profil utilisateur recueillies avec la réponse. Par défaut, il s’agit du prénom et du nom. Vous pouvez recueillir des champs de profil supplémentaires dans les paramètres du formulaire, sous Données du répondant. Si le formulaire utilise des réponses confidentielles, aucune information utilisateur n’est incluse.
-
Réponses : réponses aux questions auxquelles il a été répondu. Chaque réponse inclut
questionIdetquestionLabel. Si vous configurez une clé de question, la réponse inclut égalementquestionKey.
Configurer une clé de question
Une clé de question facilite la lecture de la charge utile et son mappage dans le système destinataire. Une clé de question doit commencer par une lettre minuscule, contenir uniquement des lettres minuscules, des chiffres et des traits de soulignement, et comporter au maximum 64 caractères. Les clés doivent être uniques au sein du formulaire, y compris les clés des questions supprimées.
- Ouvrez le formulaire dans l’Éditeur.
- Sélectionnez une question, puis sélectionnez l’icône en forme de crayon pour ouvrir les paramètres de la question.
- Saisissez la Clé de question.
- Publiez ou mettez à jour le formulaire pour que la modification prenne effet.
Les livraisons déjà en file d’attente conservent leurs clés d’origine.
Sécuriser votre webhook
Écouter un webhook signifie exposer une URL sur le web. Staffbase signe chaque charge utile avec votre secret de webhook afin que votre système puisse vérifier l’authenticité d’une requête avant de la traiter. Pour vérifier une requête :
- Lisez les en-têtes de requête
X-Staffbase-Webhook-Timestamp,X-Staffbase-Webhook-Delivery-Id,X-Staffbase-Webhook-Key-IdetX-Staffbase-Webhook-Signature. - Décodez le secret de base64url en octets.
-
Calculez le HMAC-SHA256 sur le préfixe UTF-8 suivant, suivi des octets exacts et inchangés du corps de la requête :
v1.<timestamp>.<deliveryId>.<keyId>.
- Encodez le résultat en base64url sans remplissage, préfixez-le avec
v1=, puis comparez-le à l’en-tête de signature à l’aide d’une comparaison à temps constant.
Staffbase recommande les protections supplémentaires suivantes pour votre récepteur :
- Validez la fraîcheur de l’horodatage, par exemple avec une tolérance de cinq minutes. L’horodatage est exprimé en secondes Unix.
- Rejetez les ID de livraison rejoués.
- Gérez les nouvelles tentatives de manière idempotente. Chaque nouvelle tentative possède un nouvel ID de livraison, mais le même
X-Staffbase-Webhook-Id. Si vous avez déjà traité cet événement, renvoyez une réponse 2xx sans le traiter à nouveau.
Commentaires
0 commentaire
Vous devez vous connecter pour laisser un commentaire.