Edge Connector

Edge connector mode polls ilert for events and delivers them to local on-premise targets via HTTP, Kafka, MQTT, script execution, or stdout.

Edge connector mode turns ilagent into a local delivery agent for ilert edge connections. Instead of pushing events from your infrastructure to ilert, the edge connector pulls events from the ilert API and delivers them to a target inside your network.

This is useful when:

• Your on-premise systems cannot be reached from the internet

• You need to fan-out ilert alert lifecycle events to internal tools (ticketing, automation, dashboards)

• You want reliable local delivery with cursor-based at-least-once semantics

Quick start

export ILERT_EDGE_CONNECTOR_KEY='iec1...'

ilagent daemon -v -v -p 8977 \
    --edge_mode http \
    --edge_http_url http://localhost:9090/webhook

The agent will poll ilert for new events and POST them to your local webhook endpoint. The -p 8977 flag enables the health/readiness endpoints for container orchestration.

Authentication

Edge connector mode requires the ILERT_EDGE_CONNECTOR_KEY environment variable. This key is obtained from an edge connection (alert action) configuration in ilert and is separate from the standard ILERT_API_KEY.

Alert action events are queued server-side for up to 7 days. If they are not polled within that timeframe, they are lost. Make sure your edge connector is running continuously or restarts promptly after downtime.

Delivery modes

HTTP

Delivers events as JSON to a local HTTP endpoint.

ilagent daemon --edge_mode http \
    --edge_http_url http://internal-service:8080/events \
    --edge_http_method POST

Flag	Description	Default
--edge_http_url	Target URL (required)	—
--edge_http_method	HTTP method	POST
--edge_http_auth_header	Header name for authentication (e.g. Authorization, X-API-Key)	—
--edge_http_auth_value	Auth header value (falls back to ILERT_EDGE_HTTP_AUTH_VALUE env var)	—

Authentication

If your target endpoint requires authentication, you can attach a custom auth header to every delivery request:

export ILERT_EDGE_HTTP_AUTH_VALUE='Bearer my-secret-token'

ilagent daemon --edge_mode http \
    --edge_http_url http://internal-service:8080/events \
    --edge_http_auth_header Authorization

The value can also be passed directly via --edge_http_auth_value, but using the environment variable is recommended to avoid exposing secrets in process listings. Both the header name and value must be set — specifying --edge_http_auth_header without a value will cause ilagent to exit with an error.

Each request includes metadata headers:

Header	Description
X-ilert-Event-Type	Event type (e.g. alert-created, alert-resolved)
X-ilert-Alert-Id	Alert ID
X-ilert-Edge-Item-Id	Unique edge item ID for deduplication

Error handling: 2xx responses are treated as success. 4xx responses (except 429) are considered non-retryable — the item is skipped and the cursor advances. 429 and 5xx responses stop the batch and retry on the next poll cycle.

Kafka

Produces events to a Kafka topic.

ilagent daemon --edge_mode kafka \
    --kafka_brokers localhost:9092 \
    --edge_topic edge-events

Flag	Description	Default
--kafka_brokers	Comma-separated broker list (required)	—
--edge_topic	Target topic (required)	—

Messages are keyed by the alert ID from the event payload. The producer uses the default partitioner, which deterministically assigns all messages with the same key to the same partition — this ensures that webhook events for a given alert are delivered in order.

MQTT

Publishes events to an MQTT topic.

ilagent daemon --edge_mode mqtt \
    -m broker.local -q 1883 \
    --mqtt_qos 1 \
    --edge_topic edge/events

Flag	Description	Default
-m	MQTT broker host (required)	—
-q	MQTT broker port	1883
--edge_topic	Target topic (required)	—
--mqtt_qos	QoS level (0, 1, 2)	0
--mqtt_username	Username	—
--mqtt_password	Password	—
--mqtt_tls	Enable TLS	—
--mqtt_ca	CA certificate path	—

QoS 0 does not provide broker acknowledgements. The cursor advances after the message is queued locally, not after broker confirmation. Use QoS 1 or 2 for stronger delivery assurance.

Script

Executes a script for each event, piping the JSON payload to stdin.

ilagent daemon --edge_mode script \
    --edge_script /opt/scripts/handle_event.sh

Flag	Description	Default
--edge_script	Path to executable script (required)	—

The script receives environment variables:

Variable	Description
ILERT_EVENT_TYPE	Event type
ILERT_ALERT_ID	Alert ID
ILERT_EDGE_ITEM_ID	Unique edge item ID
ILERT_TIMESTAMP	Event timestamp

The full JSON payload is written to stdin. Scripts have a 30-second execution timeout — if exceeded, the process is killed and the delivery is retried.

Example script:

#!/usr/bin/env bash
PAYLOAD=$(cat)
echo "$PAYLOAD" >> /var/log/ilert-events.jsonl

Stdout

Prints each event's JSON payload to stdout — useful for testing, debugging, or piping into other tools.

ilagent daemon --edge_mode stdout

No additional flags are required. Each polled item is printed as a single JSON line:

{"eventType":"alert-created","id":"100","summary":"Server down","status":"PENDING","timestamp":"2026-05-04T10:00:00.000Z"}

Payload format

The JSON payload delivered via all modes (HTTP request body, Kafka/MQTT message value, script stdin) follows the same structure as the ilert custom webhook payload. See Webhook payload for the full schema and field reference.

Health and readiness

Pass -p <port> to enable the HTTP server with health/readiness endpoints:

ilagent daemon -p 8977 --edge_mode http --edge_http_url http://localhost:9090/webhook

Endpoint	Description
GET /health	Returns 204 while running, 503 during shutdown
GET /ready	Returns 204 when polling successfully, 503 with diagnostics on error

The /ready endpoint returns structured JSON on failure:

{
  "component": "edge_connector",
  "polling": false,
  "error": "authentication failed — check integration key"
}

Heartbeat

Use -b to send regular heartbeat pings alongside the edge connector:

ilagent daemon -p 8977 -b il1hbt123... \
    --edge_mode http \
    --edge_http_url http://localhost:9090/webhook

This lets you monitor the ilagent process itself via ilert heartbeat monitoring.

High availability

Edge connector supports server-managed HA with leader election:

# Instance 1
ilagent daemon --edge_mode http \
    --edge_http_url http://localhost:9090/webhook \
    --edge_cluster_id prod-cluster \
    --edge_instance_id node-1

# Instance 2
ilagent daemon --edge_mode http \
    --edge_http_url http://localhost:9090/webhook \
    --edge_cluster_id prod-cluster \
    --edge_instance_id node-2

Flag	Description	Default
--edge_cluster_id	Cluster identifier (enables HA)	(disabled)
--edge_instance_id	Unique instance ID	auto-generated UUID
--edge_standby_interval	Standby poll interval	10s

The ilert API manages leader election. Only the leader receives events — standby instances poll at the standby interval waiting to be promoted. If the leader stops reporting, a standby is promoted automatically.

In HA mode, the cursor is managed server-side (not persisted locally in SQLite).

Polling configuration

Flag	Description	Default	Range
--edge_poll_interval	Seconds between polls	10	5–120
--edge_standby_interval	Seconds between standby polls (HA)	10	5–120

When a poll returns a full batch (100 items), the edge connector immediately re-polls without waiting — up to 10 consecutive times to drain backlogs. After that, it pauses for one poll interval to prevent starvation.

On consecutive poll failures, the agent applies exponential backoff (starting at 5s, capped at 300s) and resets on the first successful poll.

Delivery semantics

• At-least-once — the cursor only advances after successful delivery. On failure, the same item is retried on the next poll cycle.

• Ordered — items within a batch are delivered sequentially. A retryable failure stops the batch; remaining items are retried in order.

• Non-retryable skip — if the delivery target returns a non-retryable error (HTTP 4xx except 429), the item is logged and skipped to prevent permanent queue blocking.

• Cursor persistence — in non-HA mode, the cursor is persisted to SQLite after each successful delivery, surviving process restarts.

Exclusive mode

Edge connector is an exclusive daemon mode. The following flags from other daemon modes cannot be combined with --edge_mode:

• Consumer topics: --event_topic, --heartbeat_topic, --policy_topic

• Consumer mappings: --event_key, --map_key_*, --map_val_*, --filter_key, --filter_val

• Consumer flags: --forward_message_payload, --mqtt_buffer, --mqtt_shared_group

• Other: --max_retries, --shift_offset

Full example

export ILERT_EDGE_CONNECTOR_KEY='iec1...'

ilagent daemon -v -v -p 8977 -b il1hbt123... \
    --edge_mode script \
    --edge_script /opt/scripts/handle_event.sh \
    --edge_cluster_id prod-cluster \
    --edge_instance_id node-1 \
    --edge_poll_interval 15

This runs the edge connector in HA mode with script delivery, health endpoints on port 8977, heartbeat monitoring, and 15-second poll intervals.