Comment puis-je configurer les webhooks 12Build ?

Que trouverez-vous dans cet article ?

• Résumé : le fonctionnement des webhooks dans 12Build.

• Conditions et public cible : ce dont vous avez besoin pour la configuration.

• La configuration : comment créer un nouveau point de terminaison.

• Le message Webhook : informations sur la livraison et la structure JSON.

• Objets disponibles : quelles données vous pouvez exploiter.

• Données relationnelles : Gérer vos propres données via l'API.

• Foire aux questions (FAQ) : Réponses aux interrogations concernant les limites et l’inactivité.

• Dépannage : Procédures à suivre en cas d’échec de la livraison.

Résumé

Les webhooks permettent de « pousser » les modifications apportées aux données 12Build directement vers des applications externes. Au lieu de récupérer manuellement les données, 12Build envoie une notification à un point de terminaison que vous avez défini dès qu'un changement pertinent survient.

Conditions et public cible

Cette fonctionnalité s’adresse aux administrateurs ou aux développeurs souhaitant intégrer 12Build à d’autres systèmes.

• Relations : seules des notifications sont envoyées pour les sous-traitants avec lesquels une relation existe (marqués d'une étoile verte, dorée ou noire).

• Limite : la fonction Webhook fonctionne jusqu'à un maximum de 3 000 relations.

Configuration

Vous configurez les webhooks dans les paramètres généraux de votre organisation.

1. Accédez aux paramètres du Profil d'entreprise.

2. Accédez à la section Webhooks.

3. Créez un nouveau webhook et spécifiez le point de terminaison souhaité (l'URL de votre application externe).

4. Sélectionnez les objets et événements spécifiques pour lesquels vous souhaitez recevoir une notification.

Le message Webhook

Lorsqu’une modification du système correspond à vos paramètres, un message JSON est envoyé.

• Garantie de livraison : en cas d’échec (absence de réponse HTTP 2xx ou délai d’attente expiré), 12Build tente de renvoyer le message jusqu’à trois fois.

• Inactif : si un webhook n'a enregistré aucune livraison réussie pendant 3 jours, il est automatiquement marqué comme inactif.

• Structure : le corps du message contient des données JSON avec des champs tels que webhookId, action, object, timestamp, ainsi que la valeur actuelle (current) et les données précédentes (previous) de l'objet.

Objets disponibles

À l'heure actuelle, vous pouvez configurer des webhooks pour les cinq objets suivants :

• Entreprise

• CompanyRelation

• CompanyRelationData

• Document

• Message

Données relationnelles

Il est possible d'ajouter des données relationnelles personnalisées aux relations, pour un usage strictement individuel.

• Gestion : il n'existe actuellement aucune interface dans 12Build permettant de gérer ces données.

• API : Utilisez les fonctions de l'API pour gérer les données relationnelles via :

  • getRelations

  • addRelationData

  • removeRelationData

  • updateRelationData

Foire aux questions (FAQ)

Question : Pourquoi ne reçois-je pas de notifications de la part de certains sous-traitants ? Réponse : Les webhooks envoient uniquement les données des entreprises marquées comme relations (favoris avec une étoile). Vérifiez si le sous-traitant en question a le statut « étoile ».

Question : Que se passe-t-il si mon serveur est temporairement hors ligne ? Réponse : 12Build tente d'envoyer le message jusqu'à quatre fois. Notez que le webhook est automatiquement désactivé après 3 jours sans livraison réussie.

Dépannage

• Symptôme : Le webhook est désactivé.

  • Cause : Aucune connexion n’a été établie avec votre point de terminaison au cours des 3 derniers jours (pas de réponse HTTP de la série 200).

  • Solution : Vérifiez l'accessibilité et les journaux de votre point de terminaison, puis réactivez le webhook dans les paramètres du Profil d'entreprise.