Aller au contenu
Réserver une démo Commencer
Réserver une démo

API et webhooks

Peerdom met à disposition une API REST et un système de webhooks pour construire vos propres intégrations. L’API sert à lire et à écrire les données de votre organisation. Les webhooks servent à recevoir une notification en temps réel dès que votre carte change.

API REST

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

Authentification

Chaque requête vers l’API doit porter une clé API dans ses en-têtes. Chaque clé agit dans le contexte d’une seule organisation.

Pour créer une clé API, rendez-vous dans Paramètres > Mes données > Clés API au sein des paramètres de l’organisation et cliquez sur Nouvelle clé API. Seules les personnes disposant du droit d’accès Propriétaire peuvent créer et gérer des clés API.

Lors de la création d’une clé, choisissez son accès :

  • Lecture seule (par défaut) : la clé peut lire les données de votre organisation. Toute requête qui modifierait quelque chose est refusée.
  • Accès complet : la clé peut lire et modifier les données de votre organisation.
Traitez les clés API comme des mots de passe, y compris celles en lecture seule, et ne les partagez jamais dans un dépôt public ni dans du code côté client.

Cas d’usage

L’API se prête à un large éventail d’intégrations :

  • Synchroniser les données organisationnelles avec votre SIRH ou votre plateforme RH
  • Exporter les rôles, les cercles et les données des collègues à des fins de reporting
  • Construire des tableaux de bord ou des outils internes sur mesure
  • Alimenter d’autres systèmes avec votre structure organisationnelle

Webhooks

Les webhooks envoient une requête HTTP POST vers votre endpoint dès qu’un événement donné se produit dans Peerdom. Configurez-les dans Paramètres > Mes données > Webhooks, au sein des paramètres de l’organisation.

Les événements disponibles

Les webhooks se déclenchent sur les opérations de création, de mise à jour et de suppression, pour trois types d’entité :

  • Rôle : Create, Update, Delete
  • Groupe (un cercle) : Create, Update, Delete
  • Collègue : Create, Update, Delete

Format de la charge utile

Chaque webhook délivre 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 exactement la forme « incoming webhook » qu’attendent les outils de discussion : elle s’intègre telle quelle dans Slack, Microsoft Teams et les outils d’automatisation comme Zapier, n8n ou Pipedream.

La charge utile n’est volontairement pas structurée par champs : il n’y a ni id, ni event, ni modifiedBy au premier niveau. Tout le détail vit dans la chaîne text ; si vous avez besoin de valeurs séparées, analysez le texte du message.

Ce que contient chaque message :

  • Création : une ligne d’en-tête, l’auteur ou l’autrice, et les champs clés de l’entité (nom, carte, etc.).
  • Mise à jour : une ligne d’en-tête, l’auteur ou l’autrice, et un différentiel champ par champ, de la forme **Field:** old → new. Les modifications de champs personnalisés sont incluses ; les champs personnalisés de type liste affichent [+] added et [-] removed.
  • Suppression : 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 du changement. Lorsque le changement vient d’une personne, le message comporte une ligne d’auteur :

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

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

Exemple. La mise à jour d’un rôle peut arriver sous cette forme :

{
  "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 illustratif : la formulation exacte de l’en-tête, le format de l’URL et les espaces peuvent varier. Pour voir la charge utile réelle que recevra votre endpoint, utilisez la fonction URL de test décrite plus bas.

Tester votre endpoint

Utilisez la fonction URL de test du panneau de configuration des webhooks pour valider votre endpoint avant d’enregistrer. Elle envoie un exemple de charge utile, de quoi confirmer que votre serveur traite correctement la requête.

Utilisez les webhooks pour déclencher vos Zaps Zapier ou vos workflows n8n en temps réel, plutôt que d'interroger l'API à intervalles réguliers.

Plateformes d’automatisation

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

  • Zapier : relie Peerdom à plus de 7 000 applications avec un constructeur de workflows visuel. Voir le guide d’intégration Zapier.
  • Pipedream : plateforme pensée pour les développeurs, avec des déclencheurs HTTP, des étapes de code personnalisé (JavaScript et Python) et une offre gratuite généreuse.
  • n8n : automatisation de workflows open source et auto-hébergeable, avec des nœuds HTTP Request et plus de 400 intégrations intégrées.

Les trois plateformes savent consommer les webhooks Peerdom et appeler l’API REST, de quoi construire des workflows bidirectionnels.

En lien