Notification handling

You can optionally configure a notification (webhook) URL with an auth token to receive updates from different functionalities, such as device connectivity status, QoD session or slice creation, deletion and so on. This way, you or your client can receive update notifications from device events and stay in control.

Subscribing to notifications

import network_as_code as nac
 
from network_as_code.models.device import Device, DeviceIpv4Addr
 
client = nac.NetworkAsCodeClient(...)
 
my_device = client.devices.get(...)
 
# Here, we will keep track of when a device gets connected
# with a limit of 5 reports
# Simply change the event_type to "ROAMING_STATUS" status whenever needed
my_subscription = client.connectivity.subscribe(
    event_type="CONNECTIVITY",
    device=my_device,
    max_num_of_reports=5,
    # Use HTTPS to send notifications
    notification_url="https://example.com/notify",
    notification_auth_token="replace-with-your-auth-token"
)

Subscription parameters

ParameterDescription
event_typeThe status type you want to check, e.g. "CONNECTIVITY" or "ROAMING_STATUS".
deviceDevice ID callback parameter.
max_num_of_reportsHow many reports will be sent to endpoint.
notification_urlCreate or provide an API endpoint (also referred as callback URL or webhook).
notification_auth_tokenA password used to identify the sender of the notification.

Notification handler

The code snippet below will set up an HTTP server with a POST endpoint. Notifications will be sent for when a device is available or not.

NOTE: The notification URL should point to the recipient's HTTP endpoint that will receive the notifications. It needs to be a web server that is configured to receive POST requests that will contain session related updates, such as session creation, deletion, duration, etc. An auth token is also required to identify the sender of the notification. The incoming POST request will contain the token as Authorization: Bearer <token> header. Network-as-Code backend will send it to the informed notification_url. Always specify this parameter when using the notification functionality.

# status_handler.py for CONNECTIVITY
 
# run with: uvicorn status_handler:app
 
from fastapi import FastAPI, Header
from pydantic import BaseModel
 
from typing_extensions import Annotated
from typing import Union
 
 
app = FastAPI()
 
class Device(BaseModel):
    phoneNumber: Optional[str] | None
    networkAccessIdentifier: Optional[str] | None
    ipv4Address: Optional[str] | None
    ipv6Address: Optional[str] | None
 
class ConnectivityEventDetail(BaseModel):
    device: Device
    subscriptionId: str
    deviceStatus: str
    terminationReason: str
 
class Event(BaseModel):
    eventType: str
    eventTime: str
    eventDetail: ConnectivityEventDetail
 
class Data(BaseModel):
    device: Device
    subscriptionId: str
    terminationReason: str
 
class Notification(BaseModel):
    id: str
    source: str
    type: str
    specversion: str
    datacontenttype: str
    time: str
    eventSubscriptionId: str
    event: Event
    data: Data
 
@app.post("/notifications")
def receive_notification(
    notification: Notification,
    authorization: Annotated[Union[str, None], Header]
):
    if authorization == "Bearer my-token":
        # We can now react to the notifications
        # based on the Notification object
        print(notification)

Good to remember: The exact implementation of the notification-URL HTTP endpoint, which listens to the incoming POST requests at the /notifications URL path, can be handled by developers as they see fit.

Where can I use a notification URL and token?

Now that you've learned what a notification URL is and how to create one, you can explore more about the functionalities that use it to notify you of important Network as Code events.

Last updated on May 23, 2024