Help Center

API & Webhooks

Peerdom provides a REST API and webhook system for building custom integrations. Use the API to read and write organizational data. Use webhooks to receive real-time notifications when your map changes.

REST API

Full API documentation is available at api.peerdom.org/v1/docs.

Authentication

Every API request requires an API key in the request headers. Each key operates within the context of a single organization.

To create an API key, go to Settings > My Data > API Keys in Organization Settings and click Create a key. Only users with Owner access rights can create and manage API keys.

API keys grant full read and write access to your organization's data. Treat them like passwords and never share them in public repositories or client-side code.

Use cases

The API supports a wide range of integrations:

  • Sync organizational data with your HRIS or people platform
  • Export roles, circles, and peer data for reporting
  • Build custom dashboards or internal tools
  • Feed organizational structure into other systems

Webhooks

Webhooks send HTTP POST requests to your endpoint whenever specific events occur in Peerdom. Configure webhooks in Settings > My Data > Webhooks within Organization Settings.

Available events

Webhooks fire for create, update, and delete operations on three entity types:

  • Role: Create, Update, Delete
  • Group (a circle): Create, Update, Delete
  • Peer: Create, Update, Delete

Payload format

Each webhook delivers an HTTP POST whose body is a single JSON object with one field, text:

{
  "text": "..."
}

The text value is a human-readable, Markdown-formatted message. This is the same “incoming webhook” shape that chat tools expect, so it drops directly into Slack, Microsoft Teams, and automation tools like Zapier, n8n, and Pipedream.

The payload is intentionally not field-structured — there is no top-level id, event, or modifiedBy. Every detail lives inside the text string, so if you need individual values, parse the message text.

What each message contains:

  • Create: a header line, the author, and the entity’s key fields (such as Name and Map).
  • Update: a header line, the author, and a per-field diff in the form **Field:** old → new. Custom field changes are included; list-type custom fields show [+] added and [-] removed.
  • Delete: a header line, the author, and the entity’s key fields at the time of deletion.

Author of the change. When a user made the change, the message includes an author line:

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

If the person has no name set, this falls back to just the email address. The author line is omitted for changes triggered automatically by the system, such as cascade updates, where there is no user context — so treat it as optional.

Example. A Role update might arrive as:

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

This example is illustrative — the exact header wording, URL format, and whitespace can vary. To see the real payload your endpoint will receive, use the Test URL feature described below.

Testing your endpoint

Use the Test URL feature in the webhook configuration panel to validate your endpoint before saving. This sends a sample payload so you can confirm your server handles the request correctly.

Set up webhooks to trigger Zapier Zaps or n8n workflows in real time, rather than polling the API on a schedule.

Automation platforms

Several no-code and low-code platforms work well with the Peerdom API:

  • Zapier: Connect Peerdom to 7,000+ apps with a visual workflow builder. See the Zapier integration guide.
  • Pipedream: Developer-friendly platform with HTTP triggers, custom code steps (JavaScript and Python), and a generous free tier.
  • n8n: Open-source and self-hostable workflow automation with HTTP Request nodes and over 400 built-in integrations.

All three platforms can consume Peerdom webhooks and call the REST API to create bidirectional workflows.