Webhooks de l'API publique

Les Webhooks de l'API publique sont un service qui vous permet de recevoir des notifications sur les changements dans votre compte, ce qui vous évite ainsi de devoir vérifier constamment via l'API publique de Rentman.

En soi, les webhooks sont simplement des URL appelées par Rentman, chaque fois qu'un élément est ajouté, modifié ou supprimé dans votre compte.

Pensez à eux comme des notifications push pour chaque événement dans votre compte, que ce soit l'ajout d'un nouveau projet, la modification d'un contact ou la suppression d'un numéro de série. Lorsque l'un de ces événements se produit, Rentman enverra un payload à l'URL que vous avez définie. Ce payload contient des détails sur l'entité ajoutée, modifiée ou supprimée, ainsi que des indications sur la manière de récupérer plus d'informations à partir de l'API publique.

Remarque : l'utilisation des webhooks nécessite des compétences et de l'expérience en programmation technique. Si vous manquez de ces compétences, nous vous recommandons de demander de l'aide à un développeur externe ou une entreprise. Veuillez noter que notre équipe de support n'est pas formée dans ce domaine et ne peut pas fournir d'aide pour la mise en œuvre des webhooks.

Configuration des Webhooks de l'API publique

  1. Pour activer les webhooks, allez dans le Screenshot 2023-11-23 at 15.56.05.png module Configuration et sélectionnez "Extensions"
  2. Faites défiler jusqu'à la section Webhooks et cliquez sur "Connecter" image-20231120-112332.png
  3. Cette fenêtre contextuelle apparaîtra : image-20231120-112310.png Ici, vous devez spécifier l'URL et vous recevrez un Token. Le champ URL est l'endroit où vous spécifiez quelle URL sera appelée par Rentman lorsqu'un élément est créé, modifié ou supprimé dans votre compte. Le Token, quant à lui, sera utilisé pour générer un digest qui devrait être utilisé côté client pour vérifier que le message provient de Rentman.
  4. Cliquez sur "Enregistrer" et fermez la fenêtre contextuelle pour activer les Webhooks.

Maîtriser les Webhooks de l'API publique

Après avoir suivi toutes les étapes ci-dessus, lorsque quelque chose est ajouté, modifié ou supprimé dans votre compte, Rentman fera un appel à l'URL spécifiée. Dans ce cas, des messages seront envoyés à https://mywebhookurl.com

Chaque message suit un format commun. Pour les créations ou mises à jour, les messages ressembleront à ceci :

{
"account": "nomdevotrecompte",
"utilisateur": {
"typeElement": "Équipe",
"id": 33,
"ref": "/equipe/33"
},
"typeÉvénement": "créer",
"typeÉlément": "Contact",
"éléments": [
{
"id": 12014,
"ref": "/contacts/12014",
"parent": null
}
],
"dateÉvénement": "2023-02-02T12:07:01+01:00"
}
Des éléments plus complexes, comme les sous-projets ou les groupes d'équipements planifiés, peuvent avoir des structures de messages plus étendues, qui incluraient également des références aux éléments parent.
{
"account": "nomdevotrecompte",
"utilisateur": {
"typeElement": "Équipe",
"id": 33,
"ref": "/equipe/33"
},
"typeÉvénement": "mettreàjour",
"typeÉlément": "NuméroSérie",
"éléments": [
{
"id": 8367,
"ref": "/numérossérie/8367",
"parent": {
"id": 12792,
"typeElement": "Équipement",
"ref": "/equipement/12792"
}
}
],
"dateÉvénement": "2023-02-02T12:03:25+01:00"
}
Lorsqu'un élément est supprimé, le message contient des détails légèrement différents dans sa section éléments :
{
"account": "nomdevotrecompte",
"utilisateur": {
"typeElement": "Équipe",
"id": 33,
"ref": "/equipe/33"
},
"typeÉvénement": "supprimer",
"typeÉlément": "PersonneContact",
"éléments": [
10,
31
],
"dateÉvénement": "2023-02-02T12:08:00+01:00"
}

Le payload contiendra toujours ces composants :

  • account - nom du compte à l'origine du message
  • user - identifiant et référence API publique de l'employé ayant initié le changement. Peut être nul pour les actions non effectuées par des utilisateurs, comme lorsqu'un document est signé numériquement
  • eventType - créer, mettre à jour ou supprimer
  • itemType - type de l'élément qui a été créé, mis à jour ou supprimé. Les types d'éléments possibles sont :
Types d'éléments possibles
  • Rendez-vous, Équipe de rendez-vous, Accessoire, Emplacement de stockage, Disponibilité de l'équipe, Ligne de facture, Contact, Contrat, Coût de projet, Numéro de série, Factuur, Fichier, Dossier, Fonction de projet, Groupe de fonctions de projet, Activité d'enregistrement du temps, Grand livre, Sous-location, Groupe d'équipements de sous-location, Équipement de sous-location, Équipement, Groupe d'équipements de projet, Équipe, Devis, Personne de contact, Équipe de projet, Véhicule de projet, Équipement de projet, Projet, Demande de projet, Équipement de demande de projet, Taux d'équipe, Facteur de taux d'équipe, Réparation, Scan de l'entrepôt, Scanner d'entrepôt, Contenu de l'ensemble d'équipements, Statut, Sous-projet, Classe de taxe, Type de projet, Enregistrement du temps, Véhicule, Mouvement de stock

Astuce Rentman : vous pouvez ajouter la valeur "ref" pour interroger facilement l'utilisateur ayant déclenché le webhook, en l'ajoutant simplement après l'URL de l'API de base https://api.rentman.net. De même, vous pouvez faire de même avec la valeur "ref" de chaque élément dans le payload.

  • items - Pour les créations et mises à jour, le message contient un tableau d'objets, où chaque objet représente un élément créé/mis à jour. L'objet contient l'ID de l'élément, la référence API publique et également un objet imbriqué de la même structure, pointant vers le parent, s'il existe. S'il n'y a pas de parent, la valeur de parent est égale à null. Pour les suppressions, items est un tableau d'entiers, contenant les ID des éléments qui ont été supprimés
  • eventDate - date et heure à laquelle l'événement s'est produit

Valider l'authenticité du payload du webhook

/* exemple de ce à quoi ressemble un en-tête Digest :
Digest: sha512=509072eee2c11804287bf807307ed360892053dde89c15ddacd9daa24c63c492963c089d54677598df4422f7d18cbd6a8ebca689841754e8ca44aee1054ddf0c
*/

// voici le corps complet de la requête
$raw_body = file_get_contents('php://input');

// séparer la valeur sur '='
$digestParts = explode('=', $_SERVER['HTTP_DIGEST']);
$algo = digestParts[0];
$digest = digestParts[1];

// Ceci est connu du client et de Rentman uniquement
$token= 'some_secret_key';
$clientGeneratedDigest = hash_hmac($algo, $raw_body, $token, false);

if($digest === $clientGeneratedDigest){
// L'appel webhook a été effectué par Rentman
}
else{
// L'appel webhook n'a pas été effectué par Rentman
}

Que faire si les URL des webhooks deviennent inaccessibles ?

Si l’URL de votre webhook devient inopérante, soit en raison d’un mauvais paramétrage, soit à cause de problèmes avec votre point de terminaison, Rentman a mis en place un système de notification pour vous aider à gérer cette situation.

Que signifient ces notifications :

"Échec de la livraison des webhooks"

image (1).png

Si votre point de terminaison de webhook échoue continuellement à répondre, vous recevrez des notifications à chaque 10ᵉ échec, jusqu’à 40 (par ex. : 10, 20, 30 et 40 échecs). Veuillez noter que ces échecs doivent être consécutifs ; une seule livraison réussie réinitialise le compteur d’échecs à zéro.

"Livraison des webhooks désactivée en raison d’échecs continus"

image (2).png

Après 50 échecs consécutifs, nous désactiverons votre point de terminaison de webhook afin d’éviter d’envoyer des webhooks vers une URL non fonctionnelle. À ce stade, vous recevrez une notification vous informant de cette désactivation.

Ces notifications ne sont visibles que par les membres du personnel ayant accès au module settingsConfiguration. Assurez-vous que les membres concernés de votre équipe aient accès à ce module pour rester à la page et résoudre rapidement tout problème.

Pour résoudre ces problèmes, vous pouvez réactiver les webhooks en mettant à jour l’URL dans la section Webhooks du module settings Configuration, de la même manière que lorsque vous activez les webhooks pour la première fois.

Astuce Rentman : assurez-vous de fournir une URL valide et fonctionnelle afin de garantir une livraison ininterrompue des webhooks.  

Cet article vous a-t-il été utile ?
Utilisateurs qui ont trouvé cela utile : 1 sur 1

Articles dans cette section