Webhooks and HTTP actions
Airgate can tell other systems what happens on the network in two ways:
- Webhooks send every event of the topics you choose (for example
auth.rejectorguest.created) as a signed JSONPOSTto an HTTPS endpoint: a SOAR, an automation platform, a Teams or Power Automate workflow, your own service. - HTTP actions (context actions) are REST calls that Airgate makes as part of a policy decision, with values from the request: open a ServiceNow incident, post to Slack, tell a firewall who logged in.
Both live on Settings › Webhooks (page Webhooks and integrations).
Before you begin
Section titled “Before you begin”- An administrator role with
admin:write(Tenant Administrator). - An HTTPS endpoint that Airgate can reach from the internet. Airgate does not follow redirects.
- For signed webhooks: a random secret shared with the receiver.
Part 1: Webhooks
Section titled “Part 1: Webhooks”Step 1: Add a webhook
Section titled “Step 1: Add a webhook”-
Open Settings › Webhooks and select the Webhooks tab.
-
Select Add webhook and fill in:
Field Value Name SOAR(required, up to 128 characters)Payload URL https://soar.contoso.com/hooks/airgate. Events are POSTed as JSON; a 2xx answer is a success.Events Exact topics, prefix.*(for exampleguest.*) or*for everythingSigning secret Optional. Empty = deliveries are not signed. Stored encrypted. Extra headers Optional, for example an API key header for the receiver Timeout (s) 1 to 60 (default 10) Max retries 0 to 10 (default 5). The form shows the backoff schedule. Verify the TLS certificate On (recommended). Add Trusted CA certificate(s) (PEM) for a private CA. Enabled On -
Save, then select Send test event on the webhook row. The receiver gets the topic
webhook.testwith the message “Test delivery from Airgate”.
Topics
Section titled “Topics”| Topic | When |
|---|---|
auth.accept, auth.reject |
RADIUS or web authentication accepted or rejected |
tacacs.authen, tacacs.author, tacacs.acct |
TACACS+ authentication, authorization, accounting |
session.start, session.update, session.stop |
Network session started, interim update, stopped (RADIUS accounting) |
endpoint.created, endpoint.updated, endpoint.profile_changed, endpoint.deleted, endpoint.bulk |
Device first seen, attributes changed, device profile changed, deleted, bulk action or import |
posture.changed |
Endpoint posture token changed |
guest.created, guest.approved, guest.expired, guest.login |
Guest account created, approved, expired; guest portal login |
cert.issued, cert.revoked |
Certificate issued or revoked |
coa.sent |
CoA or Disconnect sent |
config.changed |
A configuration object changed |
system.alert |
System alert |
nad.problem |
Network device problem (unknown device, wrong shared secret) |
admin.audit |
Administrator audit record |
What the receiver gets
Section titled “What the receiver gets”POST /hooks/airgate HTTP/1.1Content-Type: application/jsonUser-Agent: NAC-Cloud-NAC-Webhook/1.0X-NAC-Event: auth.rejectX-NAC-Delivery: 7d0c1f8e-2b5a-4c3e-9f1d-0a6b8e4c2d11X-NAC-Timestamp: 1763560800X-NAC-Signature: sha256=5f2c…
{"id":"…","topic":"auth.reject","time":"2026-11-19T14:00:00Z","tenant_id":"…","tenant":"contoso","data":{…}}data is the event payload. Credentials are redacted from payloads.
Verify the signature
Section titled “Verify the signature”X-NAC-Signature is sha256= followed by the hex HMAC-SHA256 of
<X-NAC-Timestamp>.<raw body> with the signing secret. Reject requests whose
signature does not match or whose timestamp is too old:
import hmac, hashlib, time
def verify(secret: bytes, timestamp: str, body: bytes, signature: str) -> bool: if abs(time.time() - int(timestamp)) > 300: return False mac = hmac.new(secret, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest() return hmac.compare_digest("sha256=" + mac, signature)Retries
Section titled “Retries”A delivery fails on a network error or a non-2xx answer. Airgate retries
network errors, 408, 429 and 5xx answers after 30 s, 1 min, 2 min… (30 s
× 2ⁿ⁻¹, at most 1 hour, ±20 %), up to Max retries. Other 4xx answers
are final. When the last attempt fails, Airgate raises a system alert
“Webhook “…” delivery of … failed after N attempt(s)“.
The Deliveries list of a webhook shows each delivery with Status
(Pending, Success, Failed), Attempts, HTTP status, the request
and the response. Redeliver sends a delivery again as a new manual
delivery (no automatic retries).
Part 2: HTTP actions
Section titled “Part 2: HTTP actions”HTTP actions have two parts: a context server (the base URL and the credentials) and context actions on it (method, path, body).
Step 1: Add a context server
Section titled “Step 1: Add a context server”- On Settings › Webhooks, select the Context servers tab and Add context server.
- Choose the type: Generic HTTP for any REST API, or a specific one (ServiceNow, Splunk HEC, Fortinet, Check Point, Palo Alto Networks Firewall / Panorama…).
- Fill in Name, Base URL (credentials and server headers are only sent to this origin), Authentication (None, Basic / user + password, Bearer token, API key or OAuth2 client credentials) and the credentials. Optional Server headers, Server parameters and Trusted CA certificate(s).
- Save and select Test connection.
Step 2: Add a context action
Section titled “Step 2: Add a context action”-
Select the Context actions tab and Add action.
-
Optional: Start from a preset: Slack message, Microsoft Teams message, Palo Alto User-ID login / logout / register role tag, Fortinet SSO login / logout, Check Point add / delete identity, ServiceNow incident, Splunk HEC event.
-
Pick the Context server and fill in:
Field Value Name Unique per server; policies reference it Method, URL For example POST/api/now/table/incident(relative to the base URL)Content type JSON, XML, form or plain text Body Template, for example {"short_description": "Quarantine %{Connection:Client-Mac-Address}", "caller_id": "%{Authentication:Username}"}Timeout per attempt (s), Retries Retries after network errors, 408,429and5xxHeaders, Parameters Override the server’s values Response attributes After a 2xx JSON answer, write values to the device: JSON path → Endpoint attribute (for example result.number→ServiceNow Incident)Templates use
%{Namespace:Attribute}(for example%{Authentication:Username},%{Connection:Client-Mac-Address},%{Connection:Client-IP-Address},%{Connection:SSID},%{Tips:Role},%{Endpoint:Category}) and bare parameters such as%{ip},%{user},%{mac},%{role},%{ssid}. Values are encoded for the content type. Unresolved references become empty. Credential attributes (passwords, MS-CHAP responses) are never available to templates. -
Save. Open the action and use the test panel: enter a Client MAC, Username or Client IP, then Render only (builds the request, sends nothing) or Send request.
Step 3: Run the action from policy
Section titled “Step 3: Run the action from policy”A policy runs an action through an HTTP enforcement profile, executed after the decision (after Accept and Reject). Create the profile and attach it to a rule through the API, because the Access policies page offers only RADIUS profiles:
POST /api/v1/t/contoso/enforcement-profilesContent-Type: application/json
{"name": "Open quarantine ticket", "type": "HTTP", "action": "ACCEPT", "config": {"context_action_id": "<id of the context action>"}}Then add the profile to the rule’s profile_ids in the enforcement policy
(PUT /api/v1/t/contoso/enforcement-policies/{id}).
Verify
Section titled “Verify”- Webhooks: the webhook row shows Last delivery, Last 24 h delivered and failed counts, and Pending retries. The Integrations tab summarises all webhooks.
- HTTP actions: the Execution log tab lists every run with Source (policy, integration, test), Subject, HTTP status, Status and latency.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
Delivery Failed, HTTP 401 / 403 |
The receiver rejected the request (missing API key header or bad signature check). | Add the header under Extra headers; check the receiver’s signature code against the format above. |
Delivery Failed with a TLS error |
The receiver’s certificate is not trusted. | Add its CA under Trusted CA certificate(s). |
Delivery error mentions egress |
The URL resolves to a loopback, link-local or otherwise blocked address. | Use a public address. |
System alert: Webhook "…": events dropped, delivery queue is full |
The receiver is too slow for the event volume. | Narrow the topics or speed up the receiver. |
Saving fails: url host changed: send the values of the sensitive headers again |
The URL now points at another host. | Re-enter the sensitive header values. |
Execution log: skipped, HTTP enforcement profile … |
The profile is missing or is not of type HTTP. |
Check the profile id in the enforcement policy. |
Execution log: failed |
The action or its server could not be resolved, or the server answered an error. | Open the log row for the request and response; test the action. |