Logo StartupKit
DE
English Deutsch Français Español Polski

Webhook-Sicherheit & Zustellung

Webhook-Signaturen verifizieren, Wiederholungsverhalten verstehen und Zustellungsprobleme beheben.

Warum das zählt

Die Signaturverifizierung beweist, dass Nutzlasten authentisch und unverändert sind. Das Verständnis des Wiederholungs- und automatischen Deaktivierungsverhaltens hilft Ihnen, robuste Integrationen zu erstellen.

Signaturen verifizieren

Jede Zustellung wird mit dem Signiergeheimnis Ihres Endpunkts mittels HMAC-SHA256 signiert. Die Signatur umfasst den Zeitstempel und den Anfragekörper, um Replay-Angriffe zu verhindern.

Der signierte Inhalt besteht aus dem ISO-8601-Zeitstempel und dem JSON-Body, verbunden durch einen Punkt:

<timestamp>.<body>

Ruby

timestamp = request.headers["X-Webhook-Timestamp"]
signature = request.headers["X-Webhook-Signature"]
body = request.body.read

expected = OpenSSL::HMAC.hexdigest("SHA256", signing_secret, "#{timestamp}.#{body}")

if ActiveSupport::SecurityUtils.secure_compare(expected, signature)
  # Signature is valid
else
  head :unauthorized
end

Node.js

const crypto = require("crypto");

function verifySignature(signingSecret, timestamp, body, signature) {
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${timestamp}.${body}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Python

import hmac
import hashlib

def verify_signature(signing_secret, timestamp, body, signature):
    expected = hmac.new(
        signing_secret.encode(),
        f"{timestamp}.{body}".encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

Replay-Angriffe verhindern

Vergleichen Sie X-Webhook-Timestamp mit der aktuellen Uhrzeit und lehnen Sie Anfragen ab, die älter als 5 Minuten sind.

Signiergeheimnis rotieren

Klicken Sie auf Geheimnis rotieren auf der Webhook-Detailseite, um ein neues Signiergeheimnis zu generieren. Das alte Geheimnis wird sofort ungültig.

So rotieren Sie ohne Ausfallzeit:

  1. Stellen Sie Ihren Endpunkt so bereit, dass er Signaturen sowohl mit dem alten als auch dem neuen Geheimnis akzeptiert
  2. Rotieren Sie das Geheimnis in Kit
  3. Überprüfen Sie, ob Zustellungen mit dem neuen Geheimnis erfolgreich sind
  4. Entfernen Sie das alte Geheimnis aus Ihrem Endpunkt

Zustellung & Wiederholungsversuche

Kit sendet die JSON-Nutzlast per POST an Ihren Endpunkt mit diesen Timeouts:

Einstellung Wert
Verbindungs-Timeout 10 Sekunden
Lese-Timeout 15 Sekunden

Eine 2xx-Antwort markiert die Zustellung als abgeschlossen. Alles andere ist ein Fehler, und wie Kit damit umgeht, hängt davon ab, ob der Fehler vorübergehend oder dauerhaft ist.

Vorübergehende Fehler (mit Wiederholung)

Vorübergehende Fehler sind Probleme, die sich wahrscheinlich von selbst beheben — Ihr Endpunkt war kurzzeitig überlastet, hat ein Timeout erreicht oder war nicht erreichbar. Kit wiederholt diese in bis zu 5 Versuchen mit polynomiellem Backoff (jede Wartezeit länger als die vorherige).

Ein Fehler gilt als vorübergehend, wenn die Antwort eine der folgenden ist:

  • HTTP 500–599 (Serverfehler)
  • HTTP 408 (Request Timeout)
  • HTTP 429 (Too Many Requests)
  • Ein Netzwerkfehler oder Timeout (Verbindung abgelehnt, DNS-Fehler, Lese-Timeout)
Versuch Verhalten
1 Sofort
2–5 Polynomiell ansteigende Wartezeiten

Dauerhafte Fehler (ohne Wiederholung)

Dauerhafte Fehler zeigen an, dass die Anfrage selbst für Ihren Endpunkt nicht akzeptabel ist und eine Wiederholung nicht hilft. Kit markiert die Zustellung sofort als fehlerhaft und wiederholt sie nicht.

Ein Fehler gilt als dauerhaft, wenn die Antwort ein beliebiger anderer 4xx-Status ist — zum Beispiel 400, 401, 404 oder 410. Wenn Ihr Endpunkt einen dieser Codes versehentlich zurückgibt, korrigieren Sie die Route oder Authentifizierung auf Ihrer Seite; Kit wiederholt erst, wenn das nächste Ereignis ausgelöst wird.

Automatische Deaktivierung

Nach 15 aufeinanderfolgenden fehlgeschlagenen Zustellungen über alle Ereignisse hinweg deaktiviert Kit den Webhook automatisch.

Bei Deaktivierung:

  • Es werden keine weiteren Zustellungen versucht
  • Der Status wechselt zu Deaktiviert mit einem disabled_at-Zeitstempel

Klicken Sie auf Fortsetzen, um den Webhook wieder zu aktivieren. Dies setzt den Fehlerzähler zurück und versetzt den Webhook wieder in den aktiven Zustand.

Zustellungsprotokolle

Jeder Webhook-Endpunkt hat einen Tab Zustellungen, der die 50 letzten Zustellungen anzeigt. Jeder Eintrag enthält:

Feld Beschreibung
Ereignis Ereignistyp, der die Zustellung ausgelöst hat
Status pending, in_progress, completed oder errored
Versuche Anzahl der Zustellungsversuche
Anfrage-Header Mit der Anfrage gesendete Header
Antwort HTTP-Statuscode oder Fehlermeldung
Zeitstempel Zeitpunkt der Erstellung der Zustellung

Zustellungsstatus

Status Bedeutung
pending Erstellt, wartet auf Versand
in_progress Wird gerade zugestellt
completed Endpunkt hat eine 2xx-Antwort zurückgegeben
errored Alle Wiederholungsversuche erschöpft oder Endpunkt hat einen dauerhaften (4xx) Fehler zurückgegeben

Datenaufbewahrung

Zustellungsprotokolle werden 30 Tage aufbewahrt und danach automatisch gelöscht. Speichern Sie Nutzlasten auf Ihrer Seite, wenn Sie eine längere Aufbewahrung benötigen.

URL-Anforderungen

  • HTTPS erforderlich — HTTP-Endpunkte werden abgelehnt
  • Nur öffentliche IPs — URLs, die auf private Adressen auflösen (localhost, 10.x.x.x, 192.168.x.x usw.), werden blockiert
  • URLs werden bei der Erstellung und vor jeder Zustellung validiert

Fehlerbehebung

Problem Ursache Lösung
Signatur stimmt nicht überein Falsches Signiergeheimnis oder Body wurde vor der Verifizierung verändert Verifizieren Sie gegen den rohen Anfragekörper mit dem aktuellen Geheimnis
Zustellungen laufen in Timeout Endpunkt braucht länger als 15 Sekunden Geben Sie sofort 200 zurück und verarbeiten Sie asynchron
Zustellung fehlerhaft ohne Wiederholung Endpunkt hat einen dauerhaften 4xx zurückgegeben (z. B. 404, 410) Korrigieren Sie Route, Authentifizierung oder Methode; nur vorübergehende Fehler (5xx, 408, 429, Netzwerk/Timeout) werden wiederholt
Webhook automatisch deaktiviert 15 aufeinanderfolgende Fehler Beheben Sie Ihren Endpunkt und klicken Sie dann auf Fortsetzen
URL abgelehnt Private IP oder HTTP-URL Verwenden Sie eine HTTPS-URL, die auf eine öffentliche IP auflöst
Ereignisse werden nicht ausgelöst Webhook pausiert oder Ereignistyp nicht abonniert Überprüfen Sie den Webhook-Status und die abonnierten Ereignisse

Auf einen Blick

  • Kopieren Sie Ihr Signiergeheimnis von der Webhook-Detailseite
  • Implementieren Sie die HMAC-SHA256-Signaturverifizierung in Ihrem Endpunkt
  • Lehnen Sie Anfragen mit Zeitstempeln ab, die älter als 5 Minuten sind
  • Geben Sie innerhalb von 15 Sekunden einen 2xx-Statuscode zurück
  • Behandeln Sie Wiederholungsversuche idempotent (Sie können dasselbe Ereignis mehr als einmal erhalten)
  • Überwachen Sie die Zustellungsprotokolle auf Fehler
  • Richten Sie Benachrichtigungen ein, wenn ein Webhook automatisch deaktiviert wird

Suchbegriff eingeben...