Zum Inhalt springen

Webhooks

Zertifikatswarnungen an jede beliebige URL schicken – als JSON oder passend formatiert für Slack und Microsoft Teams. Für Ablauf-, Health- und CT-Warnungen.

Per Webhook geht jede Benachrichtigung zusätzlich zur E-Mail an eine URL Ihrer Wahl. Verfügbar im Tarif Pro, mit bis zu 10 Webhooks – der Ops-Kanal in Slack, eine PagerDuty-Anbindung und der Empfänger eines Kunden können also gleichzeitig jede Benachrichtigung erhalten.

Einrichten

  1. Öffnen Sie Einstellungen → Webhooks.
  2. Geben Sie unter Webhook hinzufügen auf Wunsch einen Namen an und fügen Sie die URL ein – die Ihres eigenen Endpunkts oder die Incoming-Webhook-URL aus Slack bzw. Teams.
  3. Wählen Sie das passende Payload-Format (siehe unten).
  4. Klicken Sie auf Webhook hinzufügen.
  5. Klicken Sie daneben auf Test senden. CertWatchr schickt eine Beispiel-Benachrichtigung im gewählten Format an die URL – so sehen Sie genau, wie eine echte Benachrichtigung ankommt.

Wiederholen Sie das für jedes Ziel. Mit Bearbeiten ändern Sie URL, Format oder Namen; schalten Sie Benachrichtigungen an diesen Webhook senden aus, pausiert er und behält Einstellungen und Verlauf; Löschen entfernt ihn. Im Zustellprotokoll darunter sehen Sie, an welchen Webhook jede Benachrichtigung ging und was er geantwortet hat.

Slack, Teams, Discord, Mattermost und Telegram

Wählen Sie das Format passend zur URL:

  • Slack: eine Slack-Nachricht, farblich nach Dringlichkeit markiert, mit Domain, Status, Restlaufzeit und Aussteller. Für Slack-Incoming-Webhook-URLs.
  • Microsoft Teams: eine Karte mit denselben Angaben. Für Teams-Incoming-Webhook-URLs.
  • Discord: ein Embed in denselben Farben. Für die Webhook-URL eines Kanals (Servereinstellungen → Integrationen → Webhooks).
  • Mattermost: die Nachricht im Slack-Format; Mattermost-Incoming-Webhooks verstehen sie direkt.
  • Telegram: eine Textnachricht von Ihrem eigenen Bot. Legen Sie ihn mit @BotFather an, fügen Sie ihn dem Chat hinzu und tragen Sie https://api.telegram.org/bot<Token>/sendMessage?chat_id=<Chat-ID> als URL ein. Die URL enthält das Bot-Token – behandeln Sie sie wie ein Passwort.
  • CertWatchr-JSON: das schlichte Format weiter unten, für eigene Endpunkte.

Auf das richtige Format kommt es an: Slack, Teams und die anderen ignorieren Felder, die sie nicht kennen, ohne eine Fehlermeldung. Schicken Sie einfaches JSON an eine Slack-URL, kommt deshalb eine leere Nachricht an statt eines Fehlers. Ist die Testnachricht leer, stimmt das Format nicht.

JSON-Payload

Pro Benachrichtigung ein POST mit JSON-Body:

{
  "event": "expiry_warning",
  "hostname": "example.com",
  "days_remaining": 12,
  "cert_expiry": "2026-07-31T23:59:59",
  "status": "warning"
}

Bei ct_new_cert kommt ein Objekt ct hinzu, mit new_count und einer Liste certs (höchstens zehn Einträge). Jeder Eintrag enthält serial_number, issuer, common_name, not_before, not_after und observed_at.

Mögliche Werte für event:

event Bedeutung
expiry_warning Das Zertifikat hat Ihre Warnschwelle erreicht.
expiry_critical Nur noch 7 Tage oder weniger.
renewal_overdue Ein kurzlebiges Zertifikat ist deutlich über den üblichen Zeitpunkt der automatischen Erneuerung hinaus.
caa_blocks_issuer DNS-CAA erlaubt die ausstellende CA nicht mehr; die nächste Erneuerung wird scheitern.
registration_expiring Die Domain läuft innerhalb von 30 Tagen beim Registrar aus (RDAP).
endpoint_mismatch Nicht alle Adressen hinter dem Hostnamen liefern dasselbe Zertifikat aus.
cert_changed Seit der letzten Prüfung wird ein anderes Zertifikat ausgeliefert.
check_error Der Host ließ sich auch nach mehreren Versuchen nicht prüfen.
ct_new_cert In einem CT-Log ist ein neues Zertifikat für den Hostnamen aufgetaucht – siehe CT-Log-Überwachung.

Zustellung

  • Es gilt dieselbe Tagesregel wie bei E-Mails: pro Domain und Art höchstens eine Nachricht in 24 Stunden.
  • Die Anfragen haben den Header Content-Type: application/json, sind aber weder authentifiziert noch signiert. Wenn Sie sichergehen wollen, dass eine Anfrage wirklich von CertWatchr kommt, bauen Sie ein langes Zufallstoken in den URL-Pfad ein (https://hooks.example.com/cw/<32-zufällige-zeichen>) und prüfen es auf Ihrer Seite.
  • Ihr Endpunkt muss innerhalb von 10 Sekunden antworten. Bestätigen Sie den Eingang also zügig mit einem 2xx-Status und erledigen Sie die eigentliche Verarbeitung danach.
  • Fehlgeschlagene Zustellungen werden nicht wiederholt. Sie erscheinen aber auf der Seite Benachrichtigungen mit HTTP-Status und Fehlermeldung – ein defekter Endpunkt fällt also auf, statt unbemerkt Nachrichten zu verschlucken.

Minimaler Empfänger

from flask import Flask, request

app = Flask(__name__)

@app.post("/cw")
def receive():
    data = request.json
    if data["event"] in ("expiry_warning", "expiry_critical"):
        notify_team(data["hostname"], data["days_remaining"])
    return "", 200

Mehrere Webhooks

Jeder Webhook erhält jede Benachrichtigung, jeweils in seinem eigenen Format. Ein Webhook, der beim Versand nicht erreichbar war, bekommt sie bei der nächsten Prüfung nach – auch wenn die anderen sie schon haben; einer, der sie hat, bekommt sie innerhalb der Sperrfrist nicht ein zweites Mal.

Webhooks gehören zum Konto, nicht zu einer Domain. Da jede Nachricht den Hostnamen enthält, können Sie Benachrichtigungen verschiedener Kunden trotzdem an unterschiedliche Ziele schicken – die Verteilung übernimmt dann Ihr Endpunkt. Siehe Zertifikate für Kunden und Projekte überwachen.

Wechseln Sie in einen Tarif ohne Webhooks, erhalten diese keine Benachrichtigungen mehr, bleiben aber auf der Seite – Sie können sie löschen oder nach einem erneuten Upgrade weiterverwenden.