Webhooks

Webhooks let IronWiFi push real-time event notifications to your application. Instead of polling the API for changes, your server receives an HTTP POST request whenever a relevant event occurs -- such as a user authenticating, a session starting, or account data changing.

Overview

┌──────────────┐    Event occurs    ┌─────────────────┐    HTTP POST    ┌──────────────┐
│  IronWiFi    │ ────────────────▶ │  Webhook Engine  │ ──────────────▶ │  Your Server │
│  Platform    │                   │                  │                 │  (endpoint)  │
└──────────────┘                   └─────────────────┘                 └──────────────┘
                                          │
                                    On failure: retry
                                    with exponential backoff

Common use cases:

Trigger a welcome email when a guest authenticates via captive portal
Update your ticketing system when authentication fails repeatedly
Sync session data to your analytics platform in real time
Disable building access when a WiFi session ends
Log events to a SIEM for security monitoring

Configuring Webhooks

Creating a webhook endpoint

Log in to the IronWiFi Console
Navigate to Account > Webhooks
Click Add Webhook
Configure:

Setting	Description
URL	Your HTTPS endpoint that will receive the webhook payloads
Events	Select which event types to subscribe to
Secret	A shared secret for verifying webhook signatures
Status	Enable or disable the webhook

Click Save

warning

Your webhook endpoint must use HTTPS. IronWiFi does not send webhooks to plain HTTP URLs to protect payload data in transit.

Endpoint requirements

Your webhook receiver must:

Accept HTTP POST requests
Return a
```
200
```
status code within 10 seconds to acknowledge receipt
Handle JSON payloads with
```
Content-Type: application/json
```
Be publicly accessible from IronWiFi's servers

Event Types

Authentication events

Event	Trigger	Use Case
`auth.accept`	User successfully authenticates	Log successful access, trigger welcome flow
`auth.reject`	Authentication attempt rejected	Alert on repeated failures, security monitoring
`auth.challenge`	RADIUS challenge issued	Track multi-step authentication flows

Session events

Event	Trigger	Use Case
`session.start`	New user session begins	Track occupancy, start billing
`session.update`	Interim accounting update received	Monitor bandwidth usage in real time
`session.end`	User session terminates	Stop billing, update access control

User events

Event	Trigger	Use Case
`user.created`	New user account created	Sync to external systems, send welcome email
`user.updated`	User account modified	Propagate changes to integrated systems
`user.deleted`	User account removed	Revoke access in connected systems

Voucher events

Event	Trigger	Use Case
`voucher.redeemed`	Voucher code used for authentication	Track voucher usage, update inventory
`voucher.expired`	Voucher reaches expiration	Clean up expired access records

Payload Format

All webhook payloads follow a consistent JSON structure:

{
  "id": "evt_abc123def456",
  "type": "auth.accept",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    // Event-specific data
  }
}

Authentication event payload

{
  "id": "evt_abc123def456",
  "type": "auth.accept",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "username": "john.doe",
    "nas_ip": "192.168.1.10",
    "nas_port": 0,
    "auth_method": "PEAP-MSCHAPv2",
    "mac_address": "AA:BB:CC:DD:EE:FF",
    "network_id": 12345,
    "reply_attributes": {
      "Session-Timeout": 3600,
      "Tunnel-Private-Group-ID": "100"
    }
  }
}

Session event payload

{
  "id": "evt_def456ghi789",
  "type": "session.end",
  "timestamp": "2024-01-15T11:30:00Z",
  "data": {
    "session_id": "sess_xyz789",
    "username": "john.doe",
    "nas_ip": "192.168.1.10",
    "mac_address": "AA:BB:CC:DD:EE:FF",
    "start_time": "2024-01-15T10:30:00Z",
    "end_time": "2024-01-15T11:30:00Z",
    "duration": 3600,
    "input_octets": 52428800,
    "output_octets": 157286400,
    "terminate_cause": "Session-Timeout"
  }
}

User event payload

{
  "id": "evt_ghi789jkl012",
  "type": "user.created",
  "timestamp": "2024-01-15T09:00:00Z",
  "data": {
    "user_id": 12345,
    "username": "jane.smith",
    "email": "jane@example.com",
    "fullname": "Jane Smith",
    "status": "enabled",
    "groups": ["Employees"]
  }
}

Signature Verification

Every webhook request includes a signature header that lets you verify the payload came from IronWiFi and was not tampered with.

How it works

IronWiFi computes an HMAC-SHA256 hash of the raw request body using your webhook secret
The hash is included in the
```
X-IronWiFi-Signature
```
header
Your server computes the same hash and compares it

Verification examples

Python

import hmac
import hashlib

def verify_webhook(payload_body, signature_header, secret):
    """Verify that the webhook payload is authentic."""
    expected = hmac.new(
        secret.encode("utf-8"),
        payload_body,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(
        f"sha256={expected}",
        signature_header
    )

# In your webhook handler:
# payload_body = request.get_data()  # Raw bytes
# signature = request.headers.get("X-IronWiFi-Signature")
# is_valid = verify_webhook(payload_body, signature, "your_webhook_secret")

Node.js

const crypto = require('crypto');

function verifyWebhook(payloadBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payloadBody)
    .digest('hex');

  const expectedSignature = `sha256=${expected}`;

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(signatureHeader)
  );
}

// In your Express handler:
// app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
//   const signature = req.headers['x-ironwifi-signature'];
//   if (!verifyWebhook(req.body, signature, 'your_webhook_secret')) {
//     return res.status(401).send('Invalid signature');
//   }
//   // Process the event
//   res.status(200).send('OK');
// });

PHP

<?php
function verifyWebhook($payloadBody, $signatureHeader, $secret) {
    $expected = 'sha256=' . hash_hmac('sha256', $payloadBody, $secret);
    return hash_equals($expected, $signatureHeader);
}

// In your webhook handler:
// $payload = file_get_contents('php://input');
// $signature = $_SERVER['HTTP_X_IRONWIFI_SIGNATURE'];
// if (!verifyWebhook($payload, $signature, 'your_webhook_secret')) {
//     http_response_code(401);
//     exit('Invalid signature');
// }
?>

warning

Always verify the webhook signature before processing the payload. Without verification, an attacker could send forged requests to your endpoint.

Retry Logic

IronWiFi retries failed webhook deliveries with exponential backoff:

Attempt	Delay After Failure
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

A delivery is considered failed if:

Your endpoint does not respond within 10 seconds
Your endpoint returns a non-2xx HTTP status code
The connection cannot be established (DNS failure, network error)

After 5 failed retries, the webhook event is marked as failed and no further attempts are made.

Handling retries in your application

Your webhook handler should be idempotent -- processing the same event twice should not cause problems. Use the

id

field in the payload to detect and skip duplicate deliveries:

processed_events = set()  # Use a database in production

def handle_webhook(payload):
    event_id = payload["id"]

    if event_id in processed_events:
        return  # Already processed, skip

    # Process the event
    process_event(payload)

    # Mark as processed
    processed_events.add(event_id)

Testing Webhooks

Using a test endpoint

During development, use a service like webhook.site or ngrok to inspect incoming webhook payloads:

Get a temporary URL from webhook.site
Configure it as your webhook endpoint in the IronWiFi Console
Trigger an event (e.g., authenticate a test user)
Inspect the received payload on webhook.site

Testing with cURL

Simulate a webhook delivery to test your handler locally:

curl -X POST http://localhost:3000/webhook \
  -H "Content-Type: application/json" \
  -H "X-IronWiFi-Signature: sha256=your_computed_signature" \
  -d '{
    "id": "evt_test_123",
    "type": "auth.accept",
    "timestamp": "2024-01-15T10:30:00Z",
    "data": {
      "username": "test.user",
      "nas_ip": "192.168.1.10",
      "auth_method": "PEAP-MSCHAPv2"
    }
  }'

Best Practices

Respond quickly -- Return
```
200
```
immediately and process the event asynchronously. Do not perform slow operations in the webhook handler itself.
Verify signatures -- Always validate the
```
X-IronWiFi-Signature
```
header before processing.
Handle duplicates -- Use the event
```
id
```
to implement idempotent processing.
Log everything -- Log received payloads and processing results for debugging.
Monitor delivery -- Check the webhook delivery status in the IronWiFi Console for failed deliveries.
Use a queue -- For high-volume deployments, push incoming webhooks to a message queue (RabbitMQ, SQS, Redis) and process them asynchronously.
Keep secrets secure -- Store your webhook secret in environment variables, not in source code.

Troubleshooting

Webhooks not received

Verify the endpoint URL is correct and publicly accessible
Check that the webhook is enabled in the IronWiFi Console
Confirm your firewall allows inbound HTTPS connections
Check if the event type you expect is selected in the webhook configuration

Signature verification failing

Ensure you are comparing against the raw request body (not a parsed/re-serialized version)
Verify the webhook secret matches exactly between IronWiFi and your code
Check that you are reading the
```
X-IronWiFi-Signature
```
header correctly

Events arriving late

Check the retry history in the IronWiFi Console -- previous delivery attempts may have failed
Verify your endpoint responds within 10 seconds
If your server was temporarily down, events will arrive after the retry delay

REST API -- API overview and authentication
API Authentication -- API key management
API Endpoints -- Complete endpoint reference
Error Codes -- API error reference
Reporting and Analytics -- Report data available via API

Was this page helpful?

Overview​

Configuring Webhooks​

Creating a webhook endpoint​

Endpoint requirements​

Event Types​

Authentication events​

Session events​

User events​

Voucher events​

Payload Format​

Authentication event payload​

Session event payload​

User event payload​

Signature Verification​

How it works​

Verification examples​

Python​

Node.js​

PHP​

Retry Logic​

Handling retries in your application​

Testing Webhooks​

Using a test endpoint​

Testing with cURL​

Best Practices​

Troubleshooting​

Webhooks not received​

Signature verification failing​

Events arriving late​

Related Topics​