Hilfecenter

API & Webhooks

Peerdom bietet eine REST API und ein Webhook-System für individuelle Integrationen. Nutze die API, um Organisationsdaten zu lesen und zu schreiben. Nutze Webhooks, um Echtzeit-Benachrichtigungen zu erhalten, wenn sich deine Karte ändert.

REST API

Die vollständige API-Dokumentation findest du unter api.peerdom.org/v1/docs.

Authentifizierung

Jede API-Anfrage erfordert einen API Key in den Request-Headern. Jeder Key ist einer einzelnen Organisation zugeordnet.

Um einen API Key zu erstellen, navigiere zu Einstellungen > Meine Daten > API-Schlüssel in den Organisationseinstellungen und klicke auf Schlüssel erstellen. Nur Benutzer mit Zugriffsrechten als Besitzerin oder Besitzer können API Keys erstellen und verwalten.

API Keys gewähren vollen Lese- und Schreibzugriff auf die Daten deiner Organisation. Behandle sie wie Passwörter und teile sie niemals in öffentlichen Repositories oder clientseitigem Code.

Anwendungsfälle

Die API unterstützt eine Vielzahl von Integrationen:

  • Organisationsdaten mit deinem HRIS oder deiner People-Plattform synchronisieren
  • Rollen, Kreise und Daten der Kolleginnen und Kollegen für das Reporting exportieren
  • Individuelle Dashboards oder interne Tools erstellen
  • Organisationsstruktur in andere Systeme einspeisen

Webhooks

Webhooks senden HTTP-POST-Anfragen an deinen Endpunkt, sobald bestimmte Ereignisse in Peerdom auftreten. Konfiguriere Webhooks unter Einstellungen > Meine Daten > Webhooks in den Organisationseinstellungen.

Verfügbare Ereignisse

  • Rolle: Create, Update, Delete
  • Gruppe: Create, Update, Delete
  • Peer: Create, Update, Delete

Payload-Format

Jeder Webhook liefert einen HTTP POST, dessen Body ein einzelnes JSON-Objekt mit einem einzigen Feld text ist:

{
  "text": "..."
}

Der Wert von text ist eine menschenlesbare, in Markdown formatierte Nachricht. Es ist dieselbe Form eines „incoming webhook”, die Chat-Tools erwarten, sodass sie sich direkt in Slack, Microsoft Teams und Automatisierungstools wie Zapier, n8n und Pipedream einfügt.

Die Payload ist bewusst nicht in Felder strukturiert - es gibt kein id, event oder modifiedBy auf oberster Ebene. Jedes Detail steckt in der Zeichenkette text. Wenn du einzelne Werte brauchst, musst du also den Nachrichtentext parsen.

Was jede Nachricht enthält:

  • Create: eine Kopfzeile, die Autorin oder den Autor und die wichtigsten Felder des Objekts (etwa Name und Karte).
  • Update: eine Kopfzeile, die Autorin oder den Autor und einen Diff pro Feld in der Form **Field:** old → new. Änderungen an benutzerdefinierten Feldern sind enthalten; benutzerdefinierte Felder vom Typ Liste zeigen [+] added und [-] removed.
  • Delete: eine Kopfzeile, die Autorin oder den Autor und die wichtigsten Felder des Objekts zum Zeitpunkt der Löschung.

Urheberin oder Urheber der Änderung. Wenn eine Person die Änderung vorgenommen hat, enthält die Nachricht eine Zeile zur Autorenschaft:

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

Ist für die Person kein Name hinterlegt, steht dort nur die E-Mail-Adresse. Bei Änderungen, die das System automatisch auslöst - etwa kaskadierende Aktualisierungen ohne Benutzerkontext -, fehlt diese Zeile. Behandle sie also als optional.

Beispiel. Eine aktualisierte Rolle kann so ankommen:

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

Dieses Beispiel dient nur zur Veranschaulichung: Der genaue Wortlaut der Kopfzeile, das URL-Format und die Leerzeichen können variieren. Um die tatsächliche Payload zu sehen, die dein Endpunkt erhält, verwende die unten beschriebene Funktion Test-Adresse.

Endpunkt testen

Verwende die Funktion Test-Adresse im Webhook-Konfigurationspanel, um deinen Endpunkt vor dem Speichern zu validieren. Dies sendet eine Beispiel-Payload, damit du bestätigen kannst, dass dein Server die Anfrage korrekt verarbeitet.

Richte Webhooks ein, um Zapier-Zaps oder n8n-Workflows in Echtzeit auszulösen, anstatt die API periodisch abzufragen.

Automatisierungsplattformen

Mehrere No-Code- und Low-Code-Plattformen funktionieren hervorragend mit der Peerdom API:

  • Zapier: Verbinde Peerdom mit über 7’000 Apps mittels eines visuellen Workflow-Builders. Siehe die Zapier-Integrationsanleitung.
  • Pipedream: Entwicklerfreundliche Plattform mit HTTP-Triggern, individuellen Code-Steps (JavaScript und Python) und einem grosszügigen kostenlosen Plan.
  • n8n: Open-Source- und selbst hostbare Workflow-Automatisierung mit HTTP-Request-Nodes und über 400 integrierten Integrationen.

Alle drei Plattformen können Peerdom-Webhooks konsumieren und die REST API aufrufen, um bidirektionale Workflows zu erstellen.

Verwandte Artikel