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

Webhook-Sicherheit & Zustellung

Webhook-Signaturen verifizieren, Wiederholungsverhalten verstehen und Zustellungsprobleme beheben.

Warum es wichtig ist

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. Deployen Sie Ihren Endpunkt so, 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 unternimmt bis zu 5 Versuche, wenn Ihr Endpunkt nicht erreichbar ist oder einen Fehler zurückgibt.

Versuch Verhalten
1 Sofort
2–5 Polynomiell ansteigende Wartezeiten
Einstellung Wert
Verbindungs-Timeout 10 Sekunden
Lese-Timeout 15 Sekunden

Eine 2xx-Antwort markiert die Zustellung als abgeschlossen. Jeder andere Statuscode oder ein Timeout markiert sie als fehlerhaft und löst einen Wiederholungsversuch aus.

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 stellt den Webhook auf aktiv.

Zustellungsprotokolle

Jeder Webhook-Endpunkt hat einen Tab Lieferungen, 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 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
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

Kurz-Checkliste

  • 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...