Webhooks
This guide explains how LEA Platform tells other systems — network access control (NAC), firewalls, ticketing, SIEM, paging or a CMDB — that a host, a rule or a result changed, and how to build, test and watch such an integration without writing code.
Before you start
- You need the Admin role. Other roles do not see webhooks at all, because their addresses and headers are sensitive.
- The other system must be reachable from the LEA server (directly or through an HTTP proxy), and you need its API documentation: the address, how to sign in, and which requests change what you want to change.
- Have a test account or a test instance of the other system if you can. You will start in Dry run anyway.
How a webhook works
A webhook is a list of events (for example Host non-compliant) and, for each event, the steps to run: one or more HTTP requests in order. A step can read values from the answer (for example the id of an endpoint) and the next step can use them. LEA Platform queues every event, merges repeated changes of the same host into one delivery with the newest state, retries when the other system is down, and keeps a log of every request and answer.
- Changes are picked up within a few seconds. A burst of thousands of changes is merged per host, so the other system receives at most one delivery per host for the newest state.
- When nothing changed since the last delivery for a host, rule or result, no request is sent.
- Deliveries for the same host, rule or result always run in order, one after the other.
- A restart of LEA Platform or a switch to another node never sends anything twice.
Create a webhook
A webhook is created from a preset (a ready-made starting point for a product) or from a blank definition, and it always starts in Dry run.
- Open Settings → Webhooks and click New webhook.
- Pick a preset for your product, or Blank webhook. Presets marked Tested against a simulator only must be checked against your product version. What each preset does and needs is in Webhook presets.
- On the Connection tab type the Name and the Base URL of the other system, for example
https://ise.example.com:9060. Fill in what the blue box at the top asks for. - Choose the Authentication and type the secrets (see Connect and sign in).
- On the Scope tab choose System-wide or the groups whose hosts this system should hear about.
- On the Events tab check which events are on and what each one sends.
- Click Create. The editor stays open on the Test tab.
You should see: the webhook in the table with the DRY RUN pill.
Tip: Requests per second and Requests at the same time on the Connection tab protect the other system. Keep the defaults (20 and 4) unless its documentation allows more.
Connect and sign in
Authentication tells LEA Platform how to prove its identity to the other system on every request.
| Type | Use it when the documentation says | You fill in |
|---|---|---|
| None | No authentication, or the address itself contains a key | Nothing |
| User name and password (basic) | HTTP Basic authentication (Cisco ISE ERS, many CMDBs) | User name, secret password |
| Bearer token | Authorization: Bearer <token> with a fixed token | Secret token |
| API key in a header | A key in a header such as X-API-Key or Authorization: Splunk <token> | Header name, Header value (empty = the token secret) |
| OAuth 2.0 client credentials | A token from a token URL with a client id and secret (ClearPass, Microsoft APIs) | Token URL, Client ID, optional Scope and Audience, secret client_secret |
| Login session (cookie or token) | First log in, then send a cookie or token with every call (FortiNAC, some firewalls) | The Login request, what to extract from its answer, and how to send it under Send the session with every request |
- Secrets are stored encrypted, never shown again and replaced by
••••••in every log and trace. A saved secret shows Saved (…1234) — leave empty to keep; type a new value only to change it, or click Remove. - Any template can use a secret as
secrets.<name>. Click Add a secret named for extra ones, for example an API key that goes into the address. - OAuth tokens and login sessions are reused until they expire. When a call answers 401, LEA Platform signs in again once and repeats the call.
- Check the server certificate stays on. If the other system uses your own certificate authority, paste its certificate under Trusted CA certificate (PEM, optional) instead of turning the check off.
Choose the events
Events are the changes in LEA Platform that make a webhook send requests, and the scope limits them to the hosts you choose.
- Open the webhook (Edit) and go to the Events tab. Events are listed in three panels: Host, Rule and Rule on host.
- Turn an event on with its switch. Click it to see its steps.
- Under Steps choose Its own steps, or Same as … to reuse the steps of another event (for example Host compliant and Host non-compliant often send the same request with a different value).
The full list is in Events. Scope rules:
- Host and Rule on host events are sent only for hosts in scope (the selected groups, including nested and dynamic members).
- Rule events about the rule itself (added, edited, turned on or off, deleted) are always sent.
- Rule failing and Rule passing count only the hosts in scope: Rule failing is sent when the first host in scope starts failing the rule, Rule passing when the last one is fixed.
Write the requests
Each step is one HTTP request: a method, an address, optional headers, query parameters and a body, all written as templates.
- In an event, open a step. Give it a short Step name (letters, digits, underscore), for example
lookup. - Choose the Method and type the URL. A URL that starts with
/is added to the base URL. - Add Headers and query values if the API needs them.
- Choose the Body type and type the body:
- JSON: every text value is a template, so the result is always valid JSON. A value that is exactly one
{{ … }}keeps its type:"{{ host.active }}"becomestrue, not"True". - Form fields: a JSON object of field names and template values.
- Text or XML: the whole body is one template.
- JSON: every text value is a template, so the result is always valid JSON. A value that is exactly one
- Under Answer, list the Expected status codes (empty means any 2xx) and add Status rules for the others.
- Under Values from the answer, read what later steps need, for example
idfromSearchResult.resources[0].id. - Use Only when to skip a step, for example
not steps.lookup.idon a create step andsteps.lookup.idon an update step.
A template is text with {{ … }} placeholders, for example /ers/config/endpoint?filter=mac.EQ.{{ mac | upper }}. What you
can use is listed in Templates. Examples:
{{ host.name }} the host name
{{ host.macs | join(',') }} all MAC addresses, comma separated
{{ 'true' if host.verified else 'false' }}
{{ steps.lookup.id }} a value read by the step named lookup
{{ state.endpoint_id }} a value remembered from an earlier delivery
{{ vars.anc_policy }} a value from the Variables tab
| Term | What it means |
|---|---|
| Decision | What LEA Platform did after a request: CONTINUE with the next step, SKIP the rest, FAIL the delivery, RETRY the same request, or GOTO another step. |
| Status rules | Map a status code (404), a class (4xx) or default to continue, skip, fail or goto:<step>; they win over the expected codes. |
| Repeat for each | Runs the step once per item of a list, for example host.macs; Call each item names the item (item by default). |
| Repeat all steps for each | On the event itself: runs the whole chain once per item, for example once per MAC address. |
| Remember for next time | Values saved for this host, rule or result and available as state.<name> on the next delivery, for example a remote id or an incident number. |
A failure with status 429, 408 or 5xx, a timeout or a network error is retried later (after 30 s, 2 min, 10 min, 30 min, up
to 8 hours, or when the other system's Retry-After says). Other failures, for example 400 or 404 without a status rule,
are not retried and show FAILED.
Check the answer and wait for changes
Checks let a step fail or branch on what the other system answered, not only on the status code.
- Checks: after the values are read, each Must be true expression is evaluated, for example
steps.verify.attr == 'false'. When it is false, Otherwise decides: Fail and retry later (the Message is shown in the log and the delivery is retried), Stop quietly (skip), or Go to step …. - Wait for a change: turn on Repeat this request until a condition is true for systems that apply a change in the background. The same request is sent again every Seconds between attempts until Until is true or the Attempts run out (the total wait is at most 60 seconds); then the checks and status rules decide.
Example for Cisco ISE: after the update step, a verify step reads the endpoint again with
GET /ers/config/endpoint/{{ steps.lookup.id }}, extracts attr with
ERSEndPoint.customAttributes.customAttributes.LEA_Compliant, repeats until steps.verify.attr == 'false', and has the check
steps.verify.attr == 'false' with the message ISE still reports LEA_Compliant={{ steps.verify.attr }}.
Try it safely with a dry run
A dry run processes real events exactly like a live webhook but sends nothing; every request it would make is recorded in the log.
- Leave Mode on Dry run (new webhooks start this way).
- Let it run on real changes for as long as you need — a day or a week — and compare the log with what the other team expects.
- When the requests are right, set Mode to Live and click Save.
Dry-run deliveries never update what the webhook remembers, so switching to live sends the current state of every host on its next change. Use Sync all hosts to send it at once.
Test one event
The Test tab runs the steps of one event for a real host or rule with the settings on screen, also unsaved ones.
-
Open the webhook and go to the Test tab (or click Test in the table).
-
Pick the Event, and the host and/or rule. Empty uses the first one.
-
Click Dry run. Nothing is sent; every step gets a simulated answer with its first expected status code (
200when none is set) and an empty body. -
To simulate the other system, fill in Simulated answers for the dry run, per step name:
{ "lookup": {"status": 200, "json": {"SearchResult": {"resources": [{"id": "abc"}]}}}, "verify": [{"json": {"attr": "true"}}, {"json": {"attr": "false"}}] }A list gives successive answers: the first call of
verifygets the first one, the next call the second, and the last one repeats. -
Click Send once to make the real requests once.
You should see: the result (Every step finished, Failed: …, …) and one row per request. Click a row for the request (with Copy as curl), the answer, the values read, checks and waits. Download trace saves everything as JSON for the other team. Template context used shows every value the templates could use.
Sync all hosts
Sync all hosts sends the current state of every managed host in scope once, through the Host sync event.
- Turn on the Host sync event (often Same as Host compliant) and enable the webhook.
- In the table click More (⋮) → Sync all hosts.
- Choose Dry run (record only) or Live, and click Start.
You should see: "N of M hosts queued" and the log filtered to the sync. A sync is always sent, even when nothing changed.
Walkthrough: Cisco ISE
This example marks every MAC address of a host in Cisco ISE as compliant or not, so an ISE authorization policy can limit non-compliant devices.
- In ISE, turn on ERS (Administration → System → Settings → API Settings), create an ERS admin account, and create the custom
endpoint attribute
LEA_Compliant(String) under Administration → Identity Management → Settings → Endpoint Custom Attributes. - In LEA Platform open Settings → Webhooks, click New webhook and pick Cisco ISE ERS – endpoint attributes.
- Type the Base URL (
https://<ise-pan>:9060), the ERS User name and thepasswordsecret. If ISE uses your own certificate authority, paste it under Trusted CA certificate. - On the Scope tab pick the groups of hosts that ISE should know about, then click Create.
- On the Test tab pick Host non-compliant and a host, and click Dry run. You should see for each MAC address:
lookup(GET), thencreate(POST) ormodify(PUT) andverify. - Click Send once. In ISE the endpoint now shows
LEA_Compliant = false(ortruefor a compliant host). - Leave the webhook in Dry run for a day and read the Log. Then set Mode to Live, click Save, and use More (⋮) → Sync all hosts → Live to send every host once.
- In ISE, add an authorization rule that uses
EndPoints:LEA_Compliant EQUALS false.
Read the log
The Log tab lists every delivery of a webhook with its status, its requests and answers, and why it was sent or skipped.
- Open Settings → Webhooks, tab Log (or Log on a webhook row).
- Pick the Webhook, and filter by status, Source (live events, sync, tests) or Event.
- Click a row to see its trace and the event it carried.
| Status | Meaning |
|---|---|
| SENT | Every step finished and the other system accepted the requests. |
| DRY RUN | Processed in dry run: nothing was sent, the trace shows what would have been. |
| RETRYING | The last attempt failed with a temporary error; the next try is shown in Details. |
| FAILED | Not retried any more: a permanent error, or 8 failed attempts. Fix the cause and click retry. |
| QUEUED | Waiting to be sent. Newer changes of the same host replace it until it is sent. |
| SENDING | Being sent right now. |
| SKIPPED | Nothing to do: no change since the last delivery, a step chose skip, the event is no longer mapped, or the webhook is disabled. |
| SYNC | Sent by Sync all hosts. |
| TEST | Sent from the Test tab; tests are never retried. |
| Retry failed | Queues every failed delivery of the last 3 days again. |
Requests also appear on the Audit page, tab Notifications, with the webhook name as Action. Every failed live attempt raises the Webhook … is failing notification; the next successful request clears it.
Webhook status
The status of a webhook shows whether it sends and whether its last deliveries worked.
| Pill | Meaning |
|---|---|
| LIVE | Enabled and sending real requests. |
| DRY RUN | Enabled; processes events but sends nothing, see Try it safely with a dry run. |
| DISABLED | Turned off: no events are queued and queued deliveries are skipped. |
| OK | The last delivery worked. |
| FAILING | 3 deliveries in a row failed, or one failed permanently (for example a wrong password). |
| NOT USED YET | Nothing was delivered since it was created or saved. |
| RE-ENTER CREDENTIALS | The webhook was converted from an earlier version and its password was not carried over. Edit it and type the password. |
Share a webhook with another team
- In the table click More (⋮) → Export. A
.webhook.jsonfile is downloaded with the definition, the scope and the group names. Secrets are never exported; only their names are listed. - On the other LEA Platform click Import, paste the file or click Open file, then Import.
The imported webhook is disabled. Groups are matched by name; a missing group is reported. Enter the secrets, test it, then enable it. More (⋮) → Clone makes a disabled copy on the same LEA Platform, secrets included.
Events
| Event | When it is sent |
|---|---|
Host enrolled (host.enrolled) | A new host registered |
| Host activated / Host deactivated | A host became managed, or stopped being managed |
| Host compliant / Host non-compliant | Every assigned rule passes / at least one fails |
| Host informative | The host has results but no pass or fail verdict |
| Host assigned / Host unassigned | Rules started to apply to a host that had none / no rule applies any more (also when the host is deactivated) |
| MAC address added / MAC address removed | The host reported new MAC addresses / some disappeared; event.macs lists them |
| Host deleted | The host was removed; host holds its last known name, MAC addresses and groups |
| Host sync | Sent by Sync all hosts |
| Rule created / Rule changed / Rule deleted | A rule was added / edited (event.changed lists the fields) / removed |
| Rule activated / Rule deactivated | A rule was turned on / off |
| Rule failing / Rule passing | The first host in scope started failing the rule / the last one was fixed; event.failing is the number of failing hosts |
| Rule fails on host / Rule passes on host | One rule started failing / passing on one host |
| Rule informative on host / Rule unassigned from host | One rule returned an informative result / no longer applies to one host |
Templates
Templates use the Jinja syntax ({{ value }}, {% if … %}…{% endif %}, filters such as upper, lower, default,
join, tojson, replace). Conditions (Only when, Must be true, Until, Repeat for each) are expressions
without braces, for example steps.lookup.id and host.active.
| Name | Contents |
|---|---|
| event | type, subject, ts, trigger (live, sync, test), status, prev, and per event macs, changed, failing |
| host | id, name, uuid, active, verified (true, false or empty), worst_severity, macs, mac (the first), os, os_version, system, ip, status, groups, group_ids |
| rule | id, uid, name, severity, tags, category, active |
| result | status (pass, fail, na, unassigned), prev, ts, results_id |
| steps | steps.<step>.status, .json, .text, .headers, .ok, .skipped and every value read by that step |
| state | Values remembered for this host, rule or result; a name that was never saved is empty |
| vars, secrets, session | The Variables tab, the secrets, and the values of the login session |
| now, epoch | The current time (ISO 8601) and Unix seconds |
| item, index | The current item of a repeat (or the name chosen under Call each item) and its position |
Values from the answer use JMESPath for JSON (SearchResult.resources[0].id), an XML path (//entry/@name,
/response/result/msg), a regular expression (first group), a response header or a cookie.
Webhooks from before this version
Webhooks created before this version (URL, key, password, groups) were converted automatically into webhooks that use the
Cisco API Proxy preset, so they keep sending the same requests: for every MAC address a lookup, then a create
or an update when the managed or compliant state changed. Their password was not carried over: they show
RE-ENTER CREDENTIALS until you type it again. Every host compliance change is still listed on the
Audit page as COMPLIANCE.
If something goes wrong
| Symptom | Fix |
|---|---|
| Create or Save shows red messages | Each message names the field, for example definition.events.host.compliant.steps[0].url. The editor opens the tab of the first one |
| Nothing appears in the log | Check that the webhook is enabled, the event is on, and the host is in scope (Scope tab). Host events follow the compliance status, which is updated about every 15 seconds |
| Everything shows SKIPPED with "No change since the last delivery" | The state did not change since it was sent. Use Sync all hosts to send it again |
| FAILED with HTTP 401 or 403 | Wrong user name, password, token or permissions. Edit the webhook, type the secret again and use Test → Send once |
| RETRYING with "Could not connect" or "Timed out" | The LEA server cannot reach the other system. Check the address, firewall and HTTP proxy |
| "TLS error" | Paste the certificate authority under Trusted CA certificate, or check the server name in the base URL |
A template error such as 'dict object' has no attribute 'name' | The value does not exist for this event (for example host in a rule event). Use host.get('name') or a default: `{{ host.name |
| A check fails with "still reports …" | The other system had not applied the change yet. Raise Attempts or Seconds between attempts under Wait for a change |
More in the API reference (/lea/webhooks).