# Edge Connector

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

```sh
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`.

{% hint style="warning" %}
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.
{% endhint %}

## Delivery modes

### HTTP

Delivers events as JSON to a local HTTP endpoint.

```sh
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:

```sh
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.

```sh
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.

```sh
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         | —       |

{% hint style="warning" %}
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.
{% endhint %}

### Script

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

```sh
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:

```bash
#!/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.

```sh
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](https://github.com/iLert/docs/blob/master/product-docs/integrations/outbound-integrations/webhook.md#payload) for the full schema and field reference.

## Health and readiness

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

```sh
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:

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

## Heartbeat

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

```sh
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:

```sh
# 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

```sh
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ilert.com/developer-docs/client-libraries/ilagent/edge-connector.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.