Zur Dokumentationsübersicht

Öffentliche API und Webhooks

Dieser Leitfaden beschreibt die aktuell verfügbare öffentliche v1-API und den vollständigen Webhook-Vertrag.

API-Schlüssel und Berechtigungen

Sende den Schlüssel im Header X-API-Key. Alternativ wird Authorization: Bearer <Schlüssel> akzeptiert. Jeder Schlüssel ist auf ein Unternehmen und ausgewählte Berechtigungen begrenzt.

Der vollständige API-Schlüssel wird nur einmal bei der Erstellung angezeigt. Speichere ihn sofort sicher; bei Verlust muss ein neuer Schlüssel erstellt werden.

curl https://manoplan.de/api/v1/customers \
  --header "X-API-Key: mp_your_key"

Verfügbare Berechtigungen

  • customers:read
  • customers:write
  • jobs:read
  • invoices:read

Verfügbare Endpunkte

MethodePfadBerechtigung
get/api/v1/customerscustomers:read
post/api/v1/customerscustomers:write
get/api/v1/customers/{id}customers:read
get/api/v1/jobsjobs:read
get/api/v1/jobs/{id}jobs:read
get/api/v1/invoicesinvoices:read
get/api/v1/invoices/{id}invoices:read

Webhook-Vertrag

ManoPlan sendet JSON-Ereignisse an aktive HTTPS-Endpunkte. Der Ereignisname steht zusätzlich im Header X-Manoplan-Event.

Das Webhook-Secret wird nur einmal beim Erstellen des Endpunkts angezeigt. Bewahre es wie ein Passwort auf und ersetze den Endpunkt, wenn es verloren geht.

Ereignisse

  • customer.created
  • job.created
  • job.status_changed
  • invoice.created

Payload-Umschlag

{
  "id": "delivery-id",
  "event": "job.status_changed",
  "createdAt": "2026-08-27T12:00:00.000Z",
  "data": {}
}

Übermittlungsheader

  • X-Manoplan-Event
  • X-Manoplan-Delivery
  • X-Manoplan-Signature

Signatur sicher prüfen

Berechne HMAC-SHA256 über den unveränderten Roh-Body, bevor JSON geparst wird. Vergleiche die Bytes in konstanter Zeit mit X-Manoplan-Signature. Verwirf die Anfrage bei fehlender oder ungültiger Signatur.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyWebhookSignature(rawBody, signature, secret) {
  if (!signature.startsWith('sha256=')) return false;
  const digest = signature.slice('sha256='.length);
  if (!/^[0-9a-f]{64}$/i.test(digest)) return false;

  const expected = createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(digest, 'hex');
  return timingSafeEqual(expected, received);
}

Zustellung, Wiederholungen und Deduplizierung

Die Zustellung erfolgt mindestens einmal. Antworte schnell mit 2xx und verarbeite jede X-Manoplan-Delivery-ID nur einmal. Bei Fehlern versucht ManoPlan die Zustellung nach dem folgenden Zeitplan erneut.

Wiederholungen: 1m → 5m → 30m → 2h → 6h