Centre d'aide

API et Webhooks

Peerdom fournit une API REST et un système de webhooks pour créer des intégrations personnalisées. Utilisez l’API pour lire et écrire des données organisationnelles. Utilisez les webhooks pour recevoir des notifications en temps réel lorsque votre Carte change.

API REST

La documentation complète de l’API est disponible sur api.peerdom.org/v1/docs.

Authentification

Chaque requête API nécessite une clé API dans les en-têtes de la requête. Chaque clé fonctionne dans le contexte d’une seule organisation.

Pour créer une clé API, rendez-vous dans Paramètres > Mes données > Clés API dans les Paramètres de l’organisation et cliquez sur Créer une clé. Seuls les utilisateurs disposant des droits d’accès propriétaire peuvent créer et gérer les clés API.

Les clés API accordent un accès complet en lecture et écriture aux données de votre organisation. Traitez-les comme des mots de passe et ne les partagez jamais dans des dépôts publics ou du code côté client.

Cas d’utilisation

L’API prend en charge un large éventail d’intégrations :

  • Synchroniser les données organisationnelles avec votre SIRH ou plateforme RH
  • Exporter les rôles, les cercles et les données des collègues pour le reporting
  • Créer des tableaux de bord personnalisés ou des outils internes
  • Alimenter d’autres systèmes avec la structure organisationnelle

Webhooks

Les webhooks envoient des requêtes HTTP POST à votre endpoint chaque fois que des événements spécifiques se produisent dans Peerdom. Configurez les webhooks dans Paramètres > Mes données > Webhooks dans les Paramètres de l’organisation.

Événements disponibles

  • Rôle : Create, Update, Delete
  • Groupe : Create, Update, Delete
  • Collègue : Create, Update, Delete

Format du payload

Chaque webhook envoie une requête HTTP POST dont le corps est un unique objet JSON comportant un seul champ, text :

{
  "text": "..."
}

La valeur de text est un message lisible par un humain, formaté en Markdown. C’est la forme d’« incoming webhook » qu’attendent les outils de discussion, elle s’intègre donc directement dans Slack, Microsoft Teams et des outils d’automatisation comme Zapier, n8n et Pipedream.

Le payload n’est volontairement pas structuré en champs - il n’y a pas de id, d’event ni de modifiedBy au niveau racine. Chaque détail se trouve dans la chaîne text ; si vous avez besoin de valeurs individuelles, analysez le texte du message.

Ce que contient chaque message :

  • Create : une ligne d’en-tête, l’auteur ou l’autrice, et les champs clés de l’entité (comme le Nom et la Carte).
  • Update : une ligne d’en-tête, l’auteur ou l’autrice, et un diff champ par champ sous la forme **Field:** old → new. Les modifications des champs personnalisés sont incluses ; les champs personnalisés de type liste affichent [+] added et [-] removed.
  • Delete : une ligne d’en-tête, l’auteur ou l’autrice, et les champs clés de l’entité au moment de la suppression.

Auteur ou autrice de la modification. Lorsqu’une personne est à l’origine de la modification, le message contient une ligne d’attribution :

**Author:** Firstname Lastname (email@example.com)

Si aucun nom n’est renseigné pour cette personne, seule l’adresse e-mail apparaît. Cette ligne est absente des modifications déclenchées automatiquement par le système, comme les mises à jour en cascade, où il n’y a pas de contexte utilisateur : considérez-la donc comme facultative.

Exemple. La mise à jour d’un rôle peut arriver ainsi :

{
  "text": "**[Role](https://app.peerdom.org/your-org/...)** was updated\n\n**Author:** Jane Doe (jane@example.com)\n\n**Name:** Engineer → Senior Engineer"
}

Cet exemple est donné à titre indicatif : la formulation exacte de l’en-tête, le format de l’URL et les espaces peuvent varier. Pour voir le payload réel que votre endpoint recevra, utilisez la fonctionnalité Tester l’URL décrite ci-dessous.

Tester votre endpoint

Utilisez la fonctionnalité Tester l’URL dans le panneau de configuration des webhooks pour valider votre endpoint avant de l’enregistrer. Cela envoie un payload d’exemple afin que vous puissiez confirmer que votre serveur traite correctement la requête.

Configurez des webhooks pour déclencher des Zaps Zapier ou des flux de travail n8n en temps réel, plutôt que d'interroger l'API selon un calendrier.

Plateformes d’automatisation

Plusieurs plateformes no-code et low-code fonctionnent bien avec l’API Peerdom :

  • Zapier : Connectez Peerdom à plus de 7 000 applications avec un constructeur de flux de travail visuel. Consultez le guide d’intégration Zapier.
  • Pipedream : Plateforme orientée développeurs avec des déclencheurs HTTP, des étapes de code personnalisé (JavaScript et Python) et un niveau gratuit généreux.
  • n8n : Automatisation de flux de travail open-source et auto-hébergeable avec des noeuds HTTP Request et plus de 400 intégrations intégrées.

Les trois plateformes peuvent consommer les webhooks Peerdom et appeler l’API REST pour créer des flux de travail bidirectionnels.

En lien