Webhooks

What is it?

Webhooks automatically notify external systems about lab events — e.g., a CI pipeline, a chat tool, or your own dashboard. As soon as something happens (a test fails, a report is ready, …), TestLabIQ sends an HTTP POST to the URL you configured.

How to use it

1. Setting one up: Settings → Webhooks → New webhook. Choose a name, target URL (https recommended), and the desired events. The target URL must be publicly reachable — see Common issues.
2. Events:
   • test.completed — test case completed (passed or failed)
   • test.failed — test case failed (in addition to test.completed)
   • sequence.completed — all test cases in a sequence completed
   • report.ready — PDF report ready
   • report.approved — PDF report approved electronically (only then visible in the client portal)
   • calibration.due — equipment calibration is expiring / has expired
3. Verifying the signature: Every request carries an HMAC-SHA256 signature over the raw body in the X-TestLabIQ-Signature header, computed with the webhook's signing secret (visible in the webhook list). This lets your endpoint verify that the call is genuine.
4. Testing: Via Send test you can trigger a sample delivery immediately.

Common issues

• "Nothing is arriving." Check the last attempt in the delivery history (expandable under the webhook): if an HTTP status is shown, it was sent — then the issue is on your endpoint's side. If it shows network error, the URL was unreachable.
• "Deliveries keep failing." Failed deliveries are retried up to 4 times with increasing delay. On persistent failures, you'll be notified. Common causes: endpoint down, wrong URL, timeout, or your server not responding with 2xx.
• "Signature verification fails." The signature is computed over the raw request body — verify before JSON parsing and with the exact secret for this webhook (not another one's).
• "Webhook is inactive." Disabled webhooks send nothing; re-enable it in the list.
• "The URL points to an internal address." TestLabIQ calls your URL from its own server. Targets that are only reachable from inside a private network — localhost, 192.168.…, 10.…, ….local, ….internal — are therefore rejected: from our data centre they would be unreachable anyway, and the call would instead point at our own infrastructure. Use a publicly reachable address (e.g. via a reverse proxy or a tunnelling service). For the same reason the URL must not contain a username or password (https://user:pass@…); authenticate using the signature we send instead. Deliveries do not follow redirects (301/302) — configure the final URL directly.
• "Blocked even though the address is correct." On a self-hosted installation inside your own network, an internal target is exactly what you want. There, the environment variable WEBHOOK_ALLOW_PRIVATE_TARGETS=true lifts the check. In the hosted service it is deliberately not set.
• Diagnosing via the support agent: The AI support can look at recent delivery attempts directly (get_webhook_deliveries tool) and answer "why didn't my webhook arrive?" without a screenshot.