Webhooks & Event Streams

Mit Webhooks kannst du externe Systeme (z. B. deinen eigenen Bot-Monitoring-Dienst, Alerting-Tools oder interne Statusseiten) automatisch benachrichtigen lassen, sobald relevante Ereignisse für deine Instanzen in KiroCloud eintreten. Dies ermöglicht dir, auf Events in Echtzeit zu reagieren, ohne die REST-API wiederholt abfragen zu müssen (Polling).

1. Webhook registrieren

Webhooks werden direkt in deinem Benutzer-Dashboard konfiguriert:

1. Gehe im Dashboard zu Einstellungen > Webhooks & Benachrichtigungen.
2. Klicke auf Webhook hinzufügen.
3. Name: Eine eindeutige Bezeichnung (z. B. "Discord Alerting Service").
4. Ziel-URL: Die HTTPS-Adresse deines Servers, an die KiroCloud die POST-Requests senden soll.
5. Subscribed Events: Wähle die Ereignisse aus, über die du benachrichtigt werden möchtest (z. B. bot.crashed).
6. Signing Secret (Empfohlen): Ein geheimer Schlüssel, mit dem KiroCloud die Payload signiert. So validierst du, dass die Anfrage authentisch ist.

2. Verfügbare Ereignisse

KiroCloud bietet folgende Event-Typen für deine verwalteten Instanzen:

• bot.crashed - Wird ausgelöst, wenn ein von dir gehosteter Discord-Bot unerwartet beendet wird oder wegen Speichermangels stoppt.
• bot.started - Wird ausgelöst, wenn ein Discord-Bot erfolgreich gestartet wurde.
• ticket.created - Wird ausgelöst, wenn ein neues Support-Ticket zu deinem Account erstellt wird.
• ticket.updated - Wird ausgelöst, wenn ein Support-Ticket beantwortet oder aktualisiert wird.

3. Payload-Struktur

Wenn ein abonniertes Ereignis eintritt, sendet KiroCloud einen HTTP POST-Request an deine Ziel-URL. Der Body ist als JSON-Objekt formatiert:

{
  "event": "bot.crashed",
  "timestamp": "2026-10-09T00:00:00.000Z",
  "data": {
    "botId": "00000000-0000-0000-0000-000000000000",
    "name": "MyCommunityBot",
    "exitCode": 1,
    "reason": "Process exited with code 1"
  }
}

4. Sicherheit & Signaturprüfung (HMAC-SHA256)

Um Man-in-the-Middle-Angriffe oder gefälschte Requests zu verhindern, signiert KiroCloud jede Webhook-Anfrage im HTTP-Header:

X-Kiro-Signature: sha256=a1b2c3d4e5f6...

Validierungsbeispiel in Node.js / Express:

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const WEBHOOK_SECRET = 'dein_signing_secret';

// Der rohe Request-Body wird für die Signaturprüfung benötigt
app.post('/webhook', express.json({ verify: (req, res, buf) => { req.rawBody = buf; }}), (req, res) => {
  const signature = req.headers['x-kiro-signature'];
  if (!signature) {
    return res.status(401).send('Missing signature');
  }

  const hash = crypto.createHmac('sha256', WEBHOOK_SECRET)
                     .update(req.rawBody)
                     .digest('hex');
  const expectedSignature = `sha256=${hash}`;

  if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
    console.log('Webhook verifiziert! Event:', req.body.event);
    res.status(200).send('OK');
  } else {
    res.status(401).send('Invalid signature');
  }
});

5. Fehlertoleranz & Retry-Verhalten

• KiroCloud erwartet einen HTTP-Statuscode im Bereich 2xx (z. B. 200 OK) innerhalb von 5 Sekunden.
• Antwortet dein Endpunkt mit 5xx oder läuft in ein Timeout, unternimmt das System automatische Wiederholungsversuche mit exponentiellem Backoff (bis zu 3 Versuche).
• Im Dashboard kannst du über die Schaltfläche „Test-Ping senden“ jederzeit die Erreichbarkeit deines Endpunkts überprüfen.