Webhooks

Webhooks ermöglichen es Systemen außerhalb von PrimeCal, deine Automatisierungsregeln automatisch auszulösen. Wenn ein externer Dienst — eine Buchungsplattform, ein CRM, ein Webshop — eine JSON-Nachricht an die Webhook-URL deiner Regel sendet, empfängt PrimeCal sie und führt die Regel aus.

Wie Webhooks funktionieren

Jede Automatisierungsregel, die den Trigger webhook.incoming verwendet, erhält ihre eigene eindeutige URL. Wenn ein Drittsystem eine signierte HTTP-POST-Anfrage mit einem JSON-Body an diese URL sendet, wird deine Regel ausgelöst.

Der Ablauf:

1. Das externe System sendet eine POST-Anfrage an deine Webhook-URL
2. PrimeCal empfängt die Nutzlast und protokolliert sie
3. Die Bedingungen der Regel werden anhand der Nutzlastdaten ausgewertet
4. Wenn Bedingungen zutreffen (oder keine vorhanden sind), wird die Aktion ausgeführt

Deine Webhook-URL finden

1. Gehe zu Dashboard → Automatisierung
2. Öffne die Regel, die du verbinden möchtest (oder erstelle eine neue mit webhook.incoming als Trigger)
3. Öffne in der Regel-Detailansicht den Tab Webhook
4. Kopiere die URL — sie sieht so aus:

   https://api.primecal.eu/api/automation/webhook/abc123xyz

Jede Regel hat ein anderes Token in der URL. Dieses Token identifiziert deine Regel, reicht aber allein nicht aus, um sie auszulösen — siehe unten.

Anfragen müssen signiert sein — ein einfaches POST schlägt fehl

Anders als bei vielen einfachen Webhook-Empfängern verlangt PrimeCal, dass jede eingehende Anfrage eine gültige HMAC-SHA256-Signatur trägt, nicht nur das URL-Token. Eine Anfrage ohne Signatur wird abgelehnt. Das erfordert mehr Aufwand als ein einfaches POST, bedeutet aber, dass ein für sich allein durchgesickertes Token nicht genügt, um deine Regel auszulösen.

Eine Webhook-Anfrage senden

Dein externes System muss eine Anfrage mit Content-Type: application/json und zwei erforderlichen Headern senden: einem Zeitstempel und einer Signatur, berechnet aus deiner Nutzlast und einem regelspezifischen Geheimnis.

Beispiel-Payload:

{
  "event": "order.completed",
  "data": {
    "order_id": "12345",
    "customer": "John Doe",
    "total": 99.99,
    "status": "paid"
  }
}

PrimeCal akzeptiert jede gültige JSON-Struktur. Die oberste Form ist flexibel — du kannst data, payload, body oder eine beliebige Verschachtelung verwenden, die du bevorzugst. Wichtig ist, dass du in deinen Bedingungen dieselben Pfade per Punktnotation referenzierst (z. B. webhook.data.order_id).

Dein Signaturgeheimnis erhalten

Die Web-App zeigt das Signaturgeheimnis deiner Regel derzeit nicht direkt an. Rufe es ab (oder rotiere es) im angemeldeten Zustand mit folgendem Aufruf:

curl -X POST https://api.primecal.eu/api/automation/rules/YOUR_RULE_ID/webhook/rotate-secret \
  -H "Authorization: Bearer YOUR_JWT_OR_API_KEY"

Das gibt ein webhookSecret zurück — speichere es sicher, denn es gibt keine Möglichkeit, es erneut anzuzeigen, ohne es zu rotieren (wodurch das alte nach einer kurzen Karenzzeit ungültig wird). Die meisten Integratoren tun dies einmal und hinterlegen das Geheimnis dann fest im sendenden System.

Die Signatur berechnen

Für jede Anfrage:

1. timestamp = aktuelle Unix-Zeit in Sekunden.
2. Baue die Zeichenkette "{timestamp}.{rawJsonBody}".
3. signature = HMAC-SHA256(webhookSecret, diese Zeichenkette), als Hex.
4. Sende X-PrimeCal-Timestamp: {timestamp} und X-PrimeCal-Signature: {signature}.

Der Zeitstempel muss innerhalb von 5 Minuten der PrimeCal-Uhr liegen, und jede signierte Anfrage kann nur einmal verwendet werden — das verhindert, dass alte, abgefangene Anfragen später erneut abgespielt werden.

Vollständige Anfrage-/Antwortbeispiele (Node.js und curl) findest du in der Webhook-API-Referenz — das ist die Seite, die du demjenigen gibst, der die sendende Seite implementiert.

Testen mit curl

Wegen der erforderlichen Signatur benötigt das Testen das Geheimnis und eine berechnete Signatur, nicht nur ein einfaches POST. Der schnellste Weg zu testen ist, die Signatur inline zu generieren:

SECRET="das webhookSecret, das du von rotate-secret erhalten hast"
BODY='{"event":"test","data":{"priority":"high","customer_id":"123"}}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

curl -X POST https://api.primecal.eu/api/automation/webhook/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -H "X-PrimeCal-Timestamp: $TS" \
  -H "X-PrimeCal-Signature: $SIG" \
  -d "$BODY"

Ersetze YOUR_TOKEN durch das Token aus dem Webhook-Tab deiner Regel. Prüfe nach dem Senden den Tab History der Regel in PrimeCal, um zu bestätigen, dass die Anfrage empfangen und protokolliert wurde.

Payload-Daten in Bedingungen verwenden

Sobald ein Webhook eintrifft, kannst du seinen Inhalt innerhalb von Bedingungen mit webhook.data per Punktnotation untersuchen:

• webhook.data.order_id → das Feld order_id unter data
• webhook.data.customer → das Feld customer unter data
• webhook.data.status → das Feld status unter data

Beispielregel: Nur handeln, wenn status gleich "paid" ist:

• Bedingungsfeld: webhook.data.status
• Operator: equals
• Wert: paid

Siehe Smart Values für eine vollständige Erklärung von Punktnotation und verschachteltem Zugriff.

Praktisches Beispiel: Buchungsbestätigung

Eine Reservierungsplattform sendet einen Webhook an PrimeCal, wenn jemand eine Schwimmbadeinheit bucht. Die Payload sieht so aus:

{
  "event": "booking.confirmed",
  "data": {
    "booking_id": "bk_001",
    "guest_name": "Sarah Connor",
    "slot": "2026-07-15T10:00:00",
    "type": "pool"
  }
}

Du möchtest alle eingehenden Schwimmbadbuchungen in Cyan einfärben, damit sie sich im Kalender abheben.

Regel-Einrichtung:

1. Trigger: webhook.incoming
2. Bedingung: webhook.data.type gleich pool
3. Aktion: Termin­farbe setzen → Cyan

Wenn das Reservierungssystem den Webhook auslöst, empfängt PrimeCal ihn, prüft, ob type pool ist, und wendet die Cyan-Farbe auf den zugehörigen Termin an.

URL-Token neu generieren vs. Signaturgeheimnis rotieren

Das sind zwei verschiedene Werte, und PrimeCal hat zwei verschiedene Vorgänge dafür:

• Das URL-Token (der Teil in der Webhook-URL) — regeneriere es über den Tab Webhook der Regel, wenn du vermutest, dass die URL selbst durchgesickert ist. Die alte URL funktioniert sofort nicht mehr.
• Das Signaturgeheimnis — rotiere es über die API (siehe oben), wenn du vermutest, dass das Geheimnis durchgesickert ist, oder vorsorglich regelmäßig. Das alte Geheimnis funktioniert für eine kurze Karenzzeit weiter, damit du das sendende System ohne Ausfall aktualisieren kannst, dann stoppt es.

Das Neugenerieren des einen betrifft das andere nicht — rotiere, was tatsächlich offengelegt wurde.

Webhook-Protokolle prüfen

Jede Webhook-Anfrage — ob sie die Aktion ausgelöst hat oder durch Bedingungen herausgefiltert wurde — wird im Audit-Trail der Regel protokolliert.

1. Öffne die Regel-Detailansicht
2. Gehe zum Tab History
3. Jeder Eintrag zeigt den Zeitstempel, die eingehende Nutzlast, welche Bedingungen ausgewertet wurden, und das Ergebnis

Das ist die erste Stelle, an der du nachsehen solltest, wenn ein Webhook nicht zu funktionieren scheint.

Fehlerbehebung

Wenn dein Webhook die Regel nicht wie erwartet auslöst, siehe Automatisierungen — Fehlerbehebung für eine vollständige Checkliste. Die häufigsten Probleme sind:

• 401 Unauthorized — fehlende oder ungültige X-PrimeCal-Signature/X-PrimeCal-Timestamp- Header, ein Zeitstempel, der mehr als 5 Minuten abweicht, oder eine Signatur, die gegen das falsche Geheimnis oder den falschen Rohtext berechnet wurde. Das erreicht nie den Tab History, da die Anfrage abgelehnt wird, bevor die Regel läuft — prüfe die eigenen Protokolle deines sendenden Systems auf die HTTP-Antwort.
• Falscher Content-Type-Header (muss application/json sein)
• Das Token in der URL stimmt nicht mit dem aktuellen Regel-Token überein
• Eine Bedingung filtert die Anfrage heraus (prüfe den Tab History auf den Grund — eine 200er-Antwort bedeutet, dass die Anfrage akzeptiert und ausgewertet wurde, nicht dass sie zutraf)