Helpcentrum

API en Webhooks

Peerdom biedt een REST API en webhooksysteem voor het bouwen van eigen integraties. Gebruik de API om organisatiegegevens te lezen en te schrijven. Gebruik webhooks om realtime meldingen te ontvangen wanneer je kaart verandert.

REST API

Volledige API-documentatie is beschikbaar op api.peerdom.org/v1/docs.

Authenticatie

Elk API-verzoek vereist een API-sleutel in de request-headers. Elke sleutel werkt binnen de context van een enkele organisatie.

Om een API-sleutel aan te maken, ga je naar Instellingen > Mijn gegevens > API-sleutels in Organisatie-instellingen en klik je op Sleutel aanmaken. Alleen gebruikers met Eigenaar/es-toegangsrechten kunnen API-sleutels aanmaken en beheren.

API-sleutels geven volledige lees- en schrijftoegang tot de gegevens van je organisatie. Behandel ze als wachtwoorden en deel ze nooit in openbare repositories of client-side code.

Toepassingen

De API ondersteunt een breed scala aan integraties:

  • Organisatiegegevens synchroniseren met je HRIS of personeelsplatform
  • Rollen, cirkels en collega-gegevens exporteren voor rapportages
  • Eigen dashboards of interne tools bouwen
  • Organisatiestructuur doorvoeren naar andere systemen

Webhooks

Webhooks sturen HTTP POST-verzoeken naar je endpoint wanneer er specifieke gebeurtenissen plaatsvinden in Peerdom. Configureer webhooks in Instellingen > Mijn gegevens > Webhooks binnen Organisatie-instellingen.

Beschikbare gebeurtenissen

  • Rol: Create, Update, Delete
  • Groep: Create, Update, Delete
  • Collega: Create, Update, Delete

Payloadformaat

Elke webhook levert een HTTP POST waarvan de body één JSON-object is met één veld, text:

{
  "text": "..."
}

De waarde van text is een voor mensen leesbaar, in Markdown opgemaakt bericht. Dit is dezelfde “incoming webhook”-vorm die chattools verwachten, waardoor het rechtstreeks werkt in Slack, Microsoft Teams en automatiseringstools zoals Zapier, n8n en Pipedream.

De payload is bewust niet in velden gestructureerd - er is geen id, event of modifiedBy op het hoogste niveau. Elk detail zit in de tekenreeks text, dus als je afzonderlijke waarden nodig hebt, moet je de berichttekst parsen.

Wat elk bericht bevat:

  • Create: een kopregel, de auteur en de belangrijkste velden van de entiteit (zoals Naam en Kaart).
  • Update: een kopregel, de auteur en een diff per veld in de vorm **Field:** old → new. Wijzigingen in aangepaste velden zijn inbegrepen; aangepaste velden van het type lijst tonen [+] added en [-] removed.
  • Delete: een kopregel, de auteur en de belangrijkste velden van de entiteit op het moment van verwijderen.

Auteur van de wijziging. Wanneer een gebruiker de wijziging heeft doorgevoerd, bevat het bericht een auteursregel:

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

Als voor die persoon geen naam is ingesteld, verschijnt alleen het e-mailadres. De auteursregel ontbreekt bij wijzigingen die het systeem automatisch activeert, zoals cascade-updates zonder gebruikerscontext - behandel hem dus als optioneel.

Voorbeeld. Een bijgewerkte rol kan er zo uitzien:

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

Dit voorbeeld is illustratief: de exacte bewoording van de kopregel, het URL-formaat en de witruimte kunnen variëren. Gebruik de Test-adres-functie die hieronder wordt beschreven om te zien welke payload je endpoint echt ontvangt.

Je endpoint testen

Gebruik de Test-adres-functie in het webhookconfiguratiepaneel om je endpoint te valideren voordat je opslaat. Dit stuurt een voorbeeldpayload zodat je kunt bevestigen dat je server het verzoek correct afhandelt.

Stel webhooks in om Zapier-Zaps of n8n-workflows in realtime te triggeren, in plaats van de API op een schema te pollen.

Automatiseringsplatforms

Verschillende no-code- en low-code-platforms werken goed samen met de Peerdom API:

  • Zapier: Verbind Peerdom met meer dan 7.000 apps met een visuele workflowbuilder. Zie de Zapier-integratiehandleiding.
  • Pipedream: Ontwikkelaarsvriendelijk platform met HTTP-triggers, aangepaste codestappen (JavaScript en Python) en een ruime gratis laag.
  • n8n: Open-source en zelf te hosten workflowautomatisering met HTTP Request-nodes en meer dan 400 ingebouwde integraties.

Alle drie de platforms kunnen Peerdom-webhooks ontvangen en de REST API aanroepen om bidirectionele workflows te creëren.

Gerelateerd