Notification handling

You can optionally configure a notification (sink) URL to receive updates from different functionalities, such as device reachability status or QoD session, deletion and so on. This way, you or your client can receive update notifications from device events and stay in control.

Subscribing to notificationsheader link

import datetime
from network_as_code import NetworkAsCodeApi

client = NetworkAsCodeApi(
    rapidapi_host="network-as-code.nokia.rapidapi.com",
    api_key="YOUR_API_KEY",
)

my_subscription = client.device_status.create_roaming_subscription(
    protocol="HTTP",
    sink="https://example.com/notifications",
    types=["org.camaraproject.device-roaming-status-subscriptions.v0.roaming-status"],
    config={
        "subscription_detail": {
            "device": {
                "phone_number": "+999991234567"
            }
        },
        "subscription_max_events": 5,
        "initial_event": True,
    },
    sink_credential={
        "access_token": "some-access-token",
        "access_token_expires_utc": (datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(days=1)).isoformat(),
        "access_token_type": "bearer",
    },
)

Subscription parametersheader link

ParametersTypeDescriptionMandatory or Optional
protocolstringIdentifier of the delivery protocol. Must be set to "HTTP".Mandatory
sinkstringThe recipient's HTTP endpoint, which is a web server configured to receive POST requests.Mandatory
typeslist of stringsList of CAMARA event types to subscribe to. For example ["org.camaraproject.device-roaming-status-subscriptions.v0.roaming-status"]. Only one event type per subscription is allowed.Mandatory
configobjectConfiguration parameters for the subscription, including subscription_detail, subscription_expire_time, subscription_max_events, and initial_event.Mandatory
config.subscription_detailobjectThe detail of the requested event subscription, containing the device object identifying the target device.Mandatory
config.subscription_expire_timeobject/stringWhen the subscription expires. Can be either a date-time object or an RFC 3339 formatted date string, for example "2025-12-03T12:27:08.312Z". Must have a time zone.Optional
config.subscription_max_eventsintegerMaximum number of notifications to be sent. Once this amount is reached, the subscription ends. If a notification is sent due to initial_event being set to true, this counts towards the maximum.Optional
config.initial_eventbooleanSet to true if you want to receive an event immediately upon subscription creation, if the current device state already matches the subscribed event type.Optional
sink_credentialobjectContains authorization information for delivery of notifications, including credential_type.Optional
sink_credential.credential_typestringThe type of credential. If provided, must be set to "ACCESSTOKEN".Optional

Notification handlerheader link

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

# run with: uvicorn status_handler:app

from fastapi import FastAPI, Header
from pydantic import BaseModel

from typing_extensions import Annotated
from typing import List, Optional, Union


app = FastAPI()

class Device(BaseModel):
    phoneNumber: Optional[str] | None
    networkAccessIdentifier: Optional[str] | None
    ipv4Address: Optional[str] | None
    ipv6Address: Optional[str] | None

class RoamingEventDetail(BaseModel):
    device: Device
    subscriptionId: str
    roaming: bool | None
    countryCode: int | None
    countryName: List[str] | None
    lastStatusTime: str | None
    terminationReason: str

class Event(BaseModel):
    eventType: str
    eventTime: str
    eventDetail: RoamingEventDetail

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?header link

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 September 18, 2026