Webhooks

Ein Webhook ist der Kanal für alle, die eine Benachrichtigung mit ihren eigenen Werkzeugen verbinden möchten: einem Skript, einer Statustafel, einem Bereitschaftssystem, einem kleinen Dienst, der ein Ticket eröffnet. Wenn eine Website ausfällt und wenn sie wieder erreichbar ist, sendet UptimeWire eine HTTP-Anfrage an die Adresse, die Sie festlegen.

Was ein Webhook überträgt

Warnungen zu Zertifikat, Domain und DNS werden nicht per Webhook gesendet. Sie erreichen Sie per E-Mail und, wenn verbunden, per Telegram.

Einrichtung

Die Adresse legen Sie in Ihrem UptimeWire-Konto fest, in den Benachrichtigungseinstellungen Ihres Profils. Nur der Kontoinhaber kann sie hinzufügen, ändern, testen oder entfernen.

1. Geben Sie die Adresse Ihres Empfängers ein. Sie muss mit https:// beginnen.
2. Klicken Sie auf „Adresse speichern“. Beim ersten Speichern wird ein Signaturschlüssel erzeugt.
3. Kopieren Sie den Signaturschlüssel in Ihren Empfänger. Er beginnt mit whsec_.
4. Klicken Sie auf „Testnachricht senden“. Das Ergebnis wird sofort angezeigt.

Die Adresse gilt für jede Website im Konto. Für eine einzelne Website können Sie keine andere Adresse wählen.

Welche Adressen akzeptiert werden

UptimeWire lehnt eine Adresse ab, die:

• nicht https:// verwendet oder einen Benutzernamen oder ein Passwort enthält;
• auf ein privates oder internes Netzwerk, auf den Rechner selbst oder auf einen Zahlentrick wie eine dezimale oder hexadezimale IP-Adresse zeigt;
• länger als 2.048 Zeichen ist.

Die Adresse wird beim Speichern geprüft und noch einmal vor dem Senden jeder Nachricht.

Die Nachricht

Die Anfrage ist ein HTTP-POST mit einem JSON-Inhalt. Dieses Beispiel dient der Veranschaulichung: Die Werte sind erfunden.

{
  "id": "4182",
  "event": "incident.opened",
  "site": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "Shop",
    "url": "https://shop.example.com"
  },
  "incident": {
    "id": "00000000-0000-0000-0000-000000000001",
    "started_at": "2026-11-01T10:15:00Z",
    "ended_at": null,
    "duration_seconds": null,
    "cause": "HTTP 503"
  }
}

Bei incident.closed hat der Inhalt dieselbe Form, wobei ended_at und duration_seconds gefüllt sind. Bei test sind site und incident gleich null. Zeiten sind in UTC angegeben.

Die id kennzeichnet die Zustellung, nicht den Vorfall. Der Teil zum Vorfall zeigt dessen Zustand zum Zeitpunkt des Sendens, ein verspätetes incident.opened kann also schon ein ended_at enthalten. Ignorieren Sie Felder, die Sie nicht kennen, damit Ihr Empfänger weiter funktioniert, wenn ein Feld hinzukommt.

Header

Die Signatur prüfen

Jeder, der Ihre Adresse erfährt, kann ihr eine Anfrage senden. Mit der Signatur kann Ihr Empfänger eine echte UptimeWire-Nachricht von einer gefälschten unterscheiden.

Die Signatur ist ein HMAC mit SHA-256, hexadezimal geschrieben. Sie wird mit Ihrem Signaturschlüssel über den Text berechnet, der aus der Zeit t, einem Punkt und dem unveränderten Inhalt besteht.

So prüfen Sie eine Nachricht:

1. Lesen Sie den unveränderten Inhalt, bevor Sie ihn als JSON auswerten. Auswerten und erneutes Schreiben kann ihn verändern.
2. Lesen Sie t und v1 aus dem Header X-UptimeWire-Signature.
3. Berechnen Sie den HMAC aus t, einem Punkt und dem unveränderten Inhalt mit Ihrem Signaturschlüssel.
4. Vergleichen Sie Ihr Ergebnis mit v1 in konstanter Zeit.
5. Weisen Sie die Nachricht zurück, wenn t mehr als fünf Minuten von Ihrer eigenen Uhr abweicht.

Wenn Sie in Ihrem Konto einen neuen Schlüssel erzeugen, funktioniert der alte sofort nicht mehr. Es gibt keine Überlappung.

Zustellung und Wiederholungen

Eine Zustellung gilt als erfolgreich, wenn Ihr Empfänger innerhalb von fünf Sekunden mit einem 2xx-Status antwortet. Alles andere ist ein Fehlschlag: ein anderer Status, eine Zeitüberschreitung, ein Zertifikatsproblem oder eine abgelehnte Verbindung. UptimeWire folgt keinen Weiterleitungen, und eine 3xx-Antwort ist ein Fehlschlag.

Eine fehlgeschlagene Nachricht wird insgesamt bis zu fünfmal versucht: sofort, dann nach 1, 5, 30 und 120 Minuten. Nach dem letzten Versuch wird sie als fehlgeschlagen markiert. UptimeWire benachrichtigt Sie darüber nicht per E-Mail, aber das Dashboard zeigt, dass eine Benachrichtigung nicht zugestellt wurde. Die Adresse wird nicht abgeschaltet.

In seltenen Fällen kann dieselbe Nachricht doppelt ankommen, und Nachrichten können in falscher Reihenfolge eintreffen. Speichern Sie die id jeder Nachricht, die Sie verarbeiten, und entscheiden Sie anhand von started_at, welcher Zustand der neuere ist.

Was Sie in Ihrem Konto sehen

Die Webhook-Karte in Ihrem Konto enthält ein Zustellprotokoll mit den letzten 20 Nachrichten. Zu jeder zeigt es die Website, die Art der Nachricht, den Status (zugestellt, fehlgeschlagen, wird wiederholt, wartet oder abgebrochen), die Zahl der Versuche und das Ergebnis, etwa „Antwort 200“.

Grenzen

• Eine Adresse pro Konto, von allen Websites gemeinsam genutzt. Nur der Kontoinhaber kann sie ändern.
• Nur Ausfall und Wiederherstellung.
• Ab dem Tarif Starter enthalten. Wechselt ein Konto in einen Tarif ohne Webhooks, werden wartende Nachrichten verworfen, und es entstehen keine neuen. Adresse und Schlüssel bleiben gespeichert, und die Nachrichten setzen nach einem Upgrade wieder ein.
• Nachrichten werden mindestens einmal gesendet, nicht genau einmal.
• UptimeWire liest die Antwort nicht, die Ihr Empfänger zurücksendet.

Fehlersuche

• „Diese Adresse ist nicht erlaubt.“ Die Adresse führt in ein privates oder internes Netzwerk. Verwenden Sie eine öffentliche Adresse.
• "The address must start with https://." Einfaches http:// wird nicht akzeptiert.
• „Die Adresse hat nicht innerhalb von 5 Sekunden geantwortet.“ Antworten Sie zuerst und erledigen Sie die langsame Arbeit danach, zum Beispiel indem Sie die Nachricht in eine Warteschlange stellen.
• „Antwort 3xx: Weiterleitungen werden nicht verfolgt.“ Tragen Sie die endgültige Adresse ein.
• Nachrichten kommen an, aber die Signatur stimmt nicht überein. Prüfen Sie, dass Sie sie über den unveränderten Inhalt berechnen und den aktuellen Schlüssel verwenden.
• „Zu viele Testnachrichten.“ Die Test-Schaltfläche ist auf fünf pro Minute begrenzt.

Telegram, Discord, Slack und Microsoft Teams sind eigene Kanäle. Was jeder von ihnen überträgt, steht in der Übersicht der Integrationen.