# Webhooks

## Was ist das?

Webhooks melden Labor-Ereignisse automatisch an externe Systeme — z. B. an eine
CI-Pipeline, ein Chat-Tool oder ein eigenes Dashboard. Sobald etwas passiert
(ein Test schlägt fehl, ein Bericht ist fertig …), sendet TestLabIQ einen
HTTP-POST an die von Ihnen hinterlegte URL.

## So benutzt man es

1. **Einrichten:** Einstellungen → Webhooks → *Neuer Webhook*. Name, Ziel-URL
   (https empfohlen) und die gewünschten Ereignisse wählen. Die Ziel-URL muss
   öffentlich erreichbar sein — siehe *Typische Probleme*.
2. **Ereignisse:**
   - `test.completed` — Testfall abgeschlossen (bestanden oder fehlgeschlagen)
   - `test.failed` — Testfall fehlgeschlagen (zusätzlich zu `test.completed`)
   - `sequence.completed` — alle Testfälle einer Sequenz abgeschlossen
   - `report.ready` — PDF-Bericht fertig
   - `report.approved` — PDF-Bericht elektronisch freigegeben (erst dann im Kundenportal sichtbar)
   - `calibration.due` — Gerätekalibrierung läuft ab / ist abgelaufen
3. **Signatur prüfen:** Jeder Request trägt im Header
   `X-TestLabIQ-Signature` eine HMAC-SHA256-Signatur über den rohen Body,
   berechnet mit dem Signatur-Secret des Webhooks (in der Webhook-Liste
   einsehbar). So verifiziert Ihr Endpunkt, dass der Aufruf echt ist.
4. **Testen:** Über *Test senden* lässt sich sofort eine Beispielzustellung
   auslösen.

## Typische Probleme

- **„Es kommt nichts an."** Prüfen Sie in der Zustell-Historie (unter dem
  Webhook aufklappbar) den letzten Versuch: Steht dort ein HTTP-Status, wurde
  gesendet — dann liegt es an Ihrem Endpunkt. Steht *Netzwerkfehler*, war die
  URL nicht erreichbar.
- **„Zustellungen schlagen wiederholt fehl."** Fehlgeschlagene Zustellungen
  werden bis zu 4-mal mit wachsendem Abstand wiederholt. Bei anhaltenden
  Fehlern werden Sie benachrichtigt. Häufige Ursachen: Endpunkt down, falsche
  URL, Zeitüberschreitung, oder Ihr Server antwortet nicht mit 2xx.
- **„Signaturprüfung schlägt fehl."** Die Signatur wird über den **rohen**
  Request-Body berechnet — verifizieren Sie vor dem JSON-Parsen und mit dem
  exakten Secret dieses Webhooks (nicht dem eines anderen).
- **„Webhook ist inaktiv."** Deaktivierte Webhooks senden nichts; in der Liste
  wieder aktivieren.
- **„Die URL zeigt auf eine interne Adresse."** TestLabIQ ruft Ihre URL vom
  eigenen Server aus auf. Ziele, die nur aus einem internen Netz erreichbar
  sind — `localhost`, `192.168.…`, `10.…`, `…​.local`, `…​.internal` — werden
  deshalb abgelehnt: aus unserem Rechenzentrum wären sie ohnehin nicht
  erreichbar, und der Aufruf würde stattdessen auf unsere eigene Infrastruktur
  zeigen. Nutzen Sie eine öffentlich erreichbare Adresse (z. B. über einen
  Reverse-Proxy oder einen Tunnel-Dienst). Aus demselben Grund darf die URL
  keinen Benutzernamen und kein Passwort enthalten (`https://user:pass@…`);
  authentifizieren Sie stattdessen über die mitgelieferte Signatur.
  Weiterleitungen (301/302) folgt die Zustellung nicht — hinterlegen Sie direkt
  die endgültige URL.
- **„Blockiert, obwohl die Adresse stimmt."** Bei einer selbst betriebenen
  Installation im eigenen Netz ist genau das gewünschte Ziel intern. Dort hebt
  die Umgebungsvariable `WEBHOOK_ALLOW_PRIVATE_TARGETS=true` die Prüfung auf.
  Im gehosteten Betrieb ist sie bewusst nicht gesetzt.
- **Diagnose über den Support-Agent:** Der KI-Support kann die jüngsten
  Zustellversuche direkt einsehen (Tool `get_webhook_deliveries`) und so
  „warum kam mein Webhook nicht an?" ohne Screenshot beantworten.

---

Quelle: https://www.testlabiq.com/hilfe/webhooks