Webhooks

The Webhooks Subsystem enables the NebularStack platform to send notifications to external systems via webhooks. Currently, webhooks can be triggered when a subscriber's NAS changes in the RADIUS packet we receive. This functionality will be expanded in the future to support additional contexts and triggers.

Users can configure webhooks by providing the following parameters:

  • Context: The context in which the webhook is triggered (currently, only radius-authentication is available).

  • Trigger: The event initiating the webhook (currently, only subscriber-nas-updated is available).

  • 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.

Creating and Managing Webhooks

To create and manage webhooks, begin by navigating to Subscriber Management > Webhooks.

This page is divided into two sections: "Webhook Worker" and "Webhooks." The Webhook Worker section provides information about the status of the worker responsible for processing webhooks. The worker can be in one of three states: "Active" if it is running, "Inactive" if it is stopped, or "Activating" if it is in the process of starting. Three buttons allow you to manage the worker: "Enable" starts the worker (disabled if it is already active), "Disable" stops it (disabled if it is inactive), and "Refresh" updates the status display.

/static/subscriber/webhooks-page.png

The Webhooks section displays a table containing all configured webhooks. Selecting a webhook entry opens the "View Webhook" dialog, which shows detailed information, including the unique Webhook ID, URL, SSL Verify status, Context and Trigger. The dialog also includes options to delete or edit the webhook configuration. The "Edit" button opens a dialog where the webhook configuration can be modified.

/static/subscriber/webhooks-view.png

To create a new webhook, click the "New Webhook" button at the bottom of the Webhooks section. This action opens a form where you can specify the Context, Trigger, URL, and SSL Verify settings. Be mindful of the following validation rules when configuring a webhook: 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.

/static/subscriber/webhooks-add.png

Subscriber Payload Example

Below is an example JSON snippet of the subscriber payload sent with webhook requests:

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

Troubleshooting

  • Ensure the worker is Active to process webhook requests.

  • Verify that the URL and SSL settings meet the validation constraints.

  • Use the "Refresh" button in the "Webhook Worker" section to update the worker status display.

For additional assistance, contact our support team.