Webhooks

Queued delivery

Instead of sending HTTP requests directly, the Core writes events to a MongoDB queue. A separate linknesis-webhook-sender container polls the queue and dispatches events concurrently via curl. This decouples the Core from slow or unreachable endpoints and provides durable delivery with full audit history.

Event types

• test_complete - summary when a test finishes
• test_error - when a test fails
• test_interval - every result interval (when enabled)
• threshold_alert - when configured thresholds are breached

All events include datetime (ISO 8601 UTC), source_probe_uuid, and destination_probe_uuid when available, plus both a type and an event field carrying the same event name - use whichever your consumer finds more natural. test_complete also includes a machine-readable summary object and a human-readable summary_text string.

Modes

• report_on_end - send a summary on completion/failure
• all_events - queue every test result interval
• thresholds - send alerts only when limits are breached

Thresholds

When mode is set to thresholds, events are queued only if a metric crosses the configured limit:

• MTR (ICMP, UDP, or TCP): packet loss %, average latency ms
• iperf3 TCP: retransmits
• iperf3 UDP: jitter ms, packet loss %

Payload example

The sender POSTs a single flat JSON object - there is no outer wrapper or envelope:

{
  "type": "test_complete",
  "event": "test_complete",
  "test_id": "20260622...",
  "status": "completed",
  "datetime": "2026-06-22T10:00:00Z",
  "test_type": "iperf3",
  "target": "8.8.8.8",
  "params": { "protocol": "tcp", "duration": 30 },
  "source_probe_uuid": "...",
  "destination_probe_uuid": "...",
  "summary": { "avg_bits_per_second": 12345678 },
  "summary_text": "TCP Summary\nAvg Bitrate: 0.10 Mbps..."
}

Per-test webhooks

Each test can define its own webhook configuration in addition to the global one. Per-test events use the test-specific URL, secret, timeout, rotation days, mode, and thresholds. They are queued with webhook_type="test" and webhook_id=<test_id>.

Authentication secret

If a webhook secret is configured, the sender includes it as a Bearer token:

Authorization: Bearer your-webhook-secret

If no secret is configured, the Authorization header is omitted.

The secret itself is never returned by GET /api/webhook_logs to a REST or MCP token, even with webhooks_read - only the GUI's own logged-in session can see it.

Receive webhooks with curl

For local testing you can listen with netcat or a small Python server. To inspect already dispatched events from the Core, query the webhook logs API:

curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  "https://core.linknesis.com/api/webhook_logs?status=sent&limit=10" | python3 -m json.tool