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.