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.

Configuration des Webhooks de l'API publique

1. Pour activer les Webhooks, allez dans le module Configuration et sélectionnez "Intégrations"
2. Faites défiler jusqu'à la section Webhooks et cliquez sur "Connecter"
3. Cette fenêtre contextuelle apparaîtra : 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"
}

{
  "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"
}

{
  "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"
}

/* 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 inopérants ?

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 :

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 wWebhooks 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.