Sicherheit

Das Wichtigste

Für einen sicheren Webhook sind vier Punkte entscheidend:

1. Verwende ausschließlich eine öffentliche https://-Adresse.
2. Teile das persönliche whsec_-Secret nur mit dem empfangenden System.
3. Lass jede eingehende Nachricht anhand der Signatur prüfen.
4. Wechsle das Secret, wenn es versehentlich offengelegt wurde oder ein Empfänger nicht mehr verwendet wird.

i-Planner ergänzt jeden HTTP-Aufruf um die benötigten Signatur-Header. Die technische Prüfung ist weiter unten mit Beispielen für Node.js, Python und PHP beschrieben.

Sichere Verbindung

Sichere Ziel-Adresse

i-Planner prüft die Ziel-Adresse beim Speichern und erneut unmittelbar vor jeder Zustellung. Zeigt die Adresse auf ein internes Netzwerk oder eine nicht erlaubte Adresse, wird der Versand zum Schutz deiner Daten abgebrochen und nicht wiederholt. Im Audit-Log steht dann BLOCKED_PRIVATE_URL.

Abgelehnt wird:

Wenn du in der Entwicklung gegen localhost testen willst, nutze einen Tunnel wie ngrok↗ oder Cloudflare Tunnel — Details unter Lokal testen↗.

Signatur prüfen – für Entwickler

Jeder i-Planner-Webhook wird nach der Standard-Webhooks-Spezifikation↗ signiert. Das persönliche Secret beginnt mit whsec_ und ist in den Webhook-Einstellungen unter HTTP-Signatur sichtbar.

Die Version des Nachrichtenformats steht separat im Header webhook-version (aktuell v1). Zur Signatur enthält der HTTP-Aufruf außerdem drei Standard-Webhooks-Header:

Die signierte Nachricht ist exakt webhook-id + "." + webhook-timestamp + "." + rawBody. Verifiziere deshalb den unveränderten Roh-Body vor dem JSON-Parsing. Der HMAC-Key sind die base64-dekodierten Bytes hinter whsec_.

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

export function verifyIPlannerWebhook({ secret, headers, rawBody }) {
  const id = headers['webhook-id']
  const timestamp = headers['webhook-timestamp']
  const timestampNumber = Number(timestamp)
  if (!id || !Number.isSafeInteger(timestampNumber)
      || Math.abs(Date.now() / 1000 - timestampNumber) > 300) return false

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
  const expected = `v1,${createHmac('sha256', key)
    .update(`${id}.${timestamp}.`)
    .update(rawBody)
    .digest('base64')}`

  return String(headers['webhook-signature'] || '').split(' ').some(candidate => {
    const a = Buffer.from(candidate)
    const b = Buffer.from(expected)
    return a.length === b.length && timingSafeEqual(a, b)
  })
}

import base64, hashlib, hmac, time

def verify_iplanner(secret, headers, raw_body):
    msg_id = headers.get('webhook-id')
    timestamp = headers.get('webhook-timestamp')
    if not msg_id or not timestamp or abs(time.time() - int(timestamp)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix('whsec_'))
    signed = msg_id.encode() + b'.' + timestamp.encode() + b'.' + raw_body
    expected = 'v1,' + base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    return any(hmac.compare_digest(candidate, expected)
               for candidate in headers.get('webhook-signature', '').split(' '))

<?php
function verifyIPlanner(string $secret, array $headers, string $rawBody): bool {
    $id = $headers['webhook-id'] ?? '';
    $timestamp = $headers['webhook-timestamp'] ?? '';
    if (!$id || !$timestamp || abs(time() - (int) $timestamp) > 300) return false;
    $key = base64_decode(preg_replace('/^whsec_/', '', $secret), true);
    if ($key === false) return false;
    $expected = 'v1,' . base64_encode(hash_hmac(
        'sha256', $id . '.' . $timestamp . '.' . $rawBody, $key, true
    ));
    foreach (explode(' ', $headers['webhook-signature'] ?? '') as $candidate) {
        if (hash_equals($expected, $candidate)) return true;
    }
    return false;
}

Secret sicher wechseln

Beim Wechsel bleibt das vorherige Secret noch 24 Stunden gültig. So kannst du das neue Secret zuerst im empfangenden System hinterlegen, ohne Zustellungen zu unterbrechen. Während dieser Übergangszeit enthält webhook-signature zwei v1-Werte; der Empfänger akzeptiert den Aufruf, sobald eine Signatur passt. Entferne das alte Secret nach Ablauf des angezeigten Zeitfensters.

Eigene HTTP-Header

Zusätzlich zur Signatur kannst du eigene Header wie Authorization oder X-API-Key hinterlegen. Sie werden bei jeder Zustellung mitgesendet. Verwende sie nur als zusätzliche Zugriffskontrolle: Die Webhook-Signatur bleibt die zuverlässige Prüfung, dass Inhalt und Absender unverändert sind. Geheimnisse gehören niemals in die URL.

Quellen einschränken

Über den Abschnitt Quellen kannst du einschränken, welche Auslöser den Webhook senden dürfen — zum Beispiel nur die REST-API, nicht aber Änderungen über die Benutzeroberfläche:

Die vollständige Beschreibung steht unter Wo wurde die Änderung ausgelöst?↗.

Weitere Empfehlungen für Entwickler