Webhooks & Event Streams

Mit Webhooks kannst du externe Systeme (z.B. deinen eigenen Discord Bot, Slack, PagerDuty oder interne Dashboards) automatisch benachrichtigen lassen, sobald bestimmte Ereignisse in KiroCloud eintreten. Dies ermöglicht dir, auf Events in Echtzeit zu reagieren, ohne die API wiederholt abfragen zu müssen (Polling).

1. Webhook registrieren

Webhooks werden im Developer Hub registriert.

1. Gehe zu Entwickler & API Hub > Webhooks.
2. Klicke auf Webhook hinzufügen.
3. Name: Eine interne Bezeichnung (z.B. "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 (Optional, aber empfohlen): Ein geheimer Schlüssel, mit dem wir den Payload signieren. So kannst du sicherstellen, dass die Anfragen wirklich von KiroCloud stammen.

2. Verfügbare Ereignisse

KiroCloud bietet aktuell folgende Event-Typen an:

• * - Alle Events (Wildcard). Abonnieren von allen Events.
• ticket.created - Wird ausgelöst, wenn ein neues Support-Ticket erstellt wird.
• ticket.updated - Wird ausgelöst, wenn ein Ticket beantwortet, geschlossen oder anderweitig aktualisiert wird.
• bot.crashed - Wird ausgelöst, wenn ein von KiroCloud gehosteter Discord-Bot abstürzt oder unerwartet beendet wird.
• bot.started - Wird ausgelöst, wenn ein Discord-Bot erfolgreich gestartet wurde.
• user.registered - Wird ausgelöst, wenn sich ein neuer Benutzer in der KiroCloud registriert.

3. Payload-Struktur

Wenn ein Ereignis eintritt, sendet KiroCloud einen HTTP POST-Request an deine Ziel-URL. Der Body ist im JSON-Format strukturiert:

{
  "event": "bot.crashed",
  "timestamp": "2026-08-15T04:20:00.000Z",
  "data": {
    "botId": "123456789012345678",
    "name": "My KiroBot",
    "exitCode": 1,
    "reason": "Out of memory"
  }
}

4. Sicherheit (Signing Secret)

Um zu validieren, dass der Request wirklich von KiroCloud kommt (und nicht von jemandem, der deine Webhook-URL erraten hat), solltest du ein Signing Secret konfigurieren.

Wenn ein Secret konfiguriert ist, sendet KiroCloud einen speziellen Header mit jedem Request:

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

Dieser Header enthält einen HMAC-SHA256 Hash des Request-Bodys, generiert mit deinem Secret. Du kannst ihn auf deiner Serverseite validieren:

Beispiel in Node.js / Express

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

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

// Wichtig: Wir brauchen den rohen Body-String zur Validierung!
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. Retries & Fehler

• KiroCloud erwartet einen HTTP Status-Code 2xx (z.B. 200 OK) innerhalb von 5 Sekunden.
• Antwortet dein Server mit 5xx oder reagiert nicht, wertet KiroCloud dies als Fehlschlag und erhöht den Failure-Counter im Admin-Panel.
• Webhooks mit zu vielen unbeantworteten Fehlschlägen werden ggf. temporär pausiert. Du kannst im Dashboard über den "Test"-Button jederzeit eine Probe-Nachricht senden, um die Verbindung zu verifizieren.