Webhooks

The Webhooks Subsystem enables the NebularStack platform to send notifications to external systems via webhooks. This functionality will be expanded in the future to support additional contexts and triggers.

Currently users can only configure a single webhook per context.

Users can configure webhooks by providing the following parameters:

Context: The context in which the webhook is triggered.
Trigger: The event initiating the webhook.
URL: The endpoint to which webhook data will be sent.

Additionally, users can monitor the status of the worker responsible for sending webhook requests. Standardized responses are used for webhook data, currently limited to the subscriber object. Webhooks use per-domain queues to ensure that one customer does not affect another.

Webhook Contexts and Triggers

Context	Trigger	Detail
radius-authentication	subscriber-authenticated	Triggered when a subscriber has successfully authenticated.
radius-authentication	subscriber-nas-updated	Triggered when a subscriber has successfully authenticated & the IP address of the NAS they are connecting from does not match their last known NAS IP.
radius-accounting	subscriber-session-start	Triggered when a subscriber starts a new accounting session.
radius-accounting	subscriber-usage-meter- triggered	Triggered when a subscriber's monthly combined usage reaches or exceeds the configured usage meter trigger threshold.

Creating and Managing Webhooks

To create and manage webhooks, navigate to Subscriber (AAA) > Webhooks.

The Webhooks page lists all configured webhooks in a table with three sortable columns - Context, Trigger and URL. Use the search box and pagination controls to locate an entry, and select any row to open that webhook.

The webhook page opens in read-only view mode and displays the webhook's Unique Webhook ID, URL, SSL Verify, Context, Trigger, HTTP Method and Authentication Method, together with the HTTP Basic Authentication Username, HTTP Basic Authentication Password and Bearer Token fields. All three credential fields are always displayed; they only hold a value for the authentication method in use - Basic Authentication populates the username and password, while Bearer Token populates the bearer token. Use the Edit button to modify the configuration or Delete to remove the webhook.

To create a webhook, click New Webhook and complete the form:

URL - the destination endpoint that will receive the webhook request.
SSL Verify - checkbox controlling whether the destination TLS/SSL certificate is verified.
Context - the event category the webhook subscribes to. A context must be selected first, as it determines the available triggers.
Trigger - the specific event within the selected context that fires the webhook. This field stays disabled until a context is chosen.
HTTP Method - the method the platform uses to call your endpoint. The dropdown offers GET, POST, PUT, PATCH and DELETE.
Authentication Method - how the platform authenticates when calling your endpoint: None, Basic Authentication or Bearer Token.
HTTP Basic Authentication Username and HTTP Basic Authentication Password - always shown, but only editable and required when the authentication method is Basic Authentication; otherwise they remain read-only.
Bearer Token - always shown, but only editable and required when the authentication method is Bearer Token; otherwise it remains read-only.

Only one webhook may be configured per context. The following URL validation rules apply: the URL must begin with either http:// or https://. If the URL contains an IP address, https:// cannot be used and SSL Verify must be set to False; conversely, if http:// is used, SSL Verify cannot be set to True. Avoid using localhost or 127.0.0.1, as the platform would then attempt to call itself instead of your service.

Click Create Webhook to save the new webhook, or Cancel to discard it.

Subscriber Payload Example

Below is an example JSON snippet of the subscriber payload sent with webhook requests. Payload fields vary by trigger.

RADIUS Authentication payload example:

{
    "timestamp": "2025-01-01T12:00:00+0200",
    "context": "radius-authentication",
    "trigger": "subscriber-nas-updated",
    "data": {
        "subscriber": {
            "id": "",
            "domain": "",
            "name": "",
            "username": "",
            "tenant_id": "",
            "virtual_id": "",
            "calling_station_id": "",
            "profile_id": "",
            "service_id": "",
            "last_known_nas_ip4": "",
            "last_known_nas_name": ""
        },
        "request": {...},
        "response": {...}
    }
}

RADIUS Accounting Session Start payload example:

{
    "timestamp": "2025-01-01T12:00:00+0200",
    "context": "radius-accounting",
    "trigger": "subscriber-session-start",
    "data": {
        "subscriber": {
            "id": "",
            "domain": "",
            "name": "",
            "username": "",
            "tenant_id": "",
            "virtual_id": "",
            "calling_station_id": "",
            "profile_id": "",
            "service_id": "",
            "last_known_nas_ip4": "",
            "last_known_nas_name": ""
        },
        "request": {...},
        "response": null
    }
}

Usage meter trigger payload example:

{
    "timestamp": "2025-01-01T12:00:00+0200",
    "context": "radius-accounting",
    "trigger": "subscriber-usage-meter-triggered",
    "data": {
        "subscriber": {
            "id": "",
            "domain": "",
            "name": "",
            "username": "",
            "tenant_id": "",
            "virtual_id": "",
            "calling_station_id": "",
            "profile_id": "",
            "service_id": "",
            "last_known_nas_ip4": "",
            "last_known_nas_name": ""
        },
        "usage-meter": {
            "monthly_combined_kb": 1048576,
            "monthly_month": "2025-01",
            "monthly_combined_trigger_kb": 1048576
        }
    }
}

Troubleshooting

Verify that the URL and SSL Verify settings meet the validation constraints described above.
Ensure the URL is publicly reachable from the platform and is not a localhost or 127.0.0.1 address.
Confirm the selected Context and Trigger correspond to the event you expect to receive.

For additional assistance, contact our support team.