Webhooks richtig bauen: Retries, Signaturen, Idempotenz.
Webhooks richtig bauen: Retries, Signaturen, Idempotenz
Ein Webhook, der keine Signaturen validiert, ist eine offene Backdoor.
Was Webhooks von normalen API-Calls unterscheidet
Bei einem API-Call fragt der Client den Server. Bei einem Webhook schickt der Server dem Client eine Nachricht – ohne dass der Client gefragt hat. Das dreht das Sicherheitsmodell um: Wer sagt, dass diese Nachricht wirklich vom erwarteten Sender kommt?
Signatur-Validierung
Der Sender generiert einen HMAC-Signaturen aus dem Request-Body und einem geteilten Secret. Der Empfänger prüft diese Signatur. Nur wer das Secret kennt, kann eine gültige Signatur erzeugen.
Stripe macht das mit Stripe-Signature Header. GitHub mit X-Hub-Signature-256. Das Pattern ist überall gleich.
Und: Timing-Attack-sichere String-Vergleiche nutzen (hash_equals() in PHP, nicht ===).
Retry-Mechanismus
Webhooks scheitern. Der empfangende Server ist down, zu langsam, gibt einen 5xx zurück. Ein robustes Webhook-System retried – mit Exponential Backoff. Nach x Retries: Dead Letter Queue oder Alert.
Als Empfänger: immer schnell antworten (202 Accepted), dann asynchron verarbeiten. Timeout-Probleme vermeiden.
Idempotenz
Was passiert, wenn ein Webhook zweimal geliefert wird (kann passieren bei Retries)? Der Empfänger muss idempotent sein. Jede Webhook-Nachricht hat eine eindeutige ID – der Empfänger speichert, welche IDs bereits verarbeitet wurden.
Checkliste Webhooks
Signatur-Validierung implementiert (HMAC)
Timing-Attack-sichere Vergleiche (hash_equals)
Idempotenz-Check auf Webhook-Event-ID
Retry-Mechanismus mit Exponential Backoff
Dead Letter Queue für nicht zustellbare Nachrichten
Schnelle Response (202 Accepted), asynchrone Verarbeitung
Webhooks bauen oder absichern?
markom.digital entwickelt robuste Webhook-Systeme – auf Sender- und Empfänger-Seite.
