Zum Hauptinhalt springen

API — Webhooks

Webhooks ermöglichen Event-basierte Integration: SpeamCore POSTet bei bestimmten Events einen JSON-Payload an Ihre URL.

Event-Typen​

EventWann
customer.createdNeuer Kunde
customer.updatedKunde geändert
customer.deletedKunde gelöscht (Soft)
workorder.completedAuftrag abgeschlossen
salesdoc.sentBeleg versendet
payment.receivedZahlung eingegangen
mahnung.sentMahnung versendet
absence.approvedUrlaub genehmigt
compliance.expiringBescheinigung läuft bald ab

Vollständige Liste in der UI unter Admin → Webhooks.

Konfiguration​

POST /api/webhooks
{
  "url": "https://my-app.example.com/speamcore-events",
  "events": ["customer.*", "workorder.completed"],
  "secret": "shared-secret-for-signature",
  "active": true
}

Wildcard-Events: customer.* — alle Customer-Events.

Payload-Format​

{
  "event": "customer.created",
  "timestamp": "2026-05-05T14:32:00Z",
  "tenantId": "uuid",
  "data": {
    "id": "uuid",
    "name": "Beispiel GmbH",
    ...
  }
}

Signatur-Verifikation​

Pro Webhook-Call wird ein Header gesetzt:

X-Speamcore-Signature: sha256=<hex>

Verifikation:

const crypto = require("crypto");
const expectedSig = "sha256=" + crypto
  .createHmac("sha256", secret)
  .update(rawBody)
  .digest("hex");

if (req.headers["x-speamcore-signature"] !== expectedSig) {
  return res.status(401).end();
}

Retry-Verhalten​

Bei Fehler (Status >= 400):

  • Retry nach 1 min
  • Retry nach 5 min
  • Retry nach 15 min
  • Retry nach 1 h
  • Retry nach 6 h
  • Aufgeben — Webhook im Log als failed markiert

Bei dauerhaften Fehlern (10 Fehlschläge in Folge): Webhook automatisch deaktiviert + Notification an Admin.

Webhook-Logs​

Pro Versand wird protokolliert:

  • Event-Typ
  • Ziel-URL
  • Status-Code
  • Response (gekürzt)
  • Latenz
  • Retry-Anzahl

UI: Admin → Webhooks → Logs.

Tipps​

  • ✅ Idempotenz im Empfänger — gleiches Event 2x verarbeitet darf nicht doppelt wirken
  • ✅ Schnell antworten (200 OK), Verarbeitung asynchron
  • ✅ Secret rotieren bei Verdacht auf Leak
  • ❌ Webhook-Empfänger nicht öffentlich (auth-pflichtig oder IP-Whitelist)
  • ❌ Sensible Daten nicht im Webhook-Body (Lohn, Bank) — separat über API holen

Beispiel-Anwendungen​

  • CRM-Sync: customer.* → eigenes CRM aktualisieren
  • Buchhaltungs-Tool: salesdoc.sent → Rechnung in Buchhaltungs-Tool importieren
  • Slack-Notification: workorder.completed → Slack-Channel benachrichtigen
  • Reporting: payment.received → Live-Dashboard aktualisieren

Verwandte Doku​