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 notifications
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 parameters
| Parameters | Type | Description | Mandatory or Optional |
|---|---|---|---|
protocol | string | Identifier of the delivery protocol. Must be set to "HTTP". | Mandatory |
sink | string | The recipient's HTTP endpoint, which is a web server configured to receive POST requests. | Mandatory |
types | list of strings | List 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 |
config | object | Configuration parameters for the subscription, including subscription_detail, subscription_expire_time, subscription_max_events, and initial_event. | Mandatory |
config.subscription_detail | object | The detail of the requested event subscription, containing the device object identifying the target device. | Mandatory |
config.subscription_expire_time | object/string | When 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_events | integer | Maximum 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_event | boolean | Set 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_credential | object | Contains authorization information for delivery of notifications, including credential_type. | Optional |
sink_credential.credential_type | string | The type of credential. If provided, must be set to "ACCESSTOKEN". | Optional |
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
POSTrequests 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 incomingPOSTrequest will contain the token asAuthorization: Bearer <token> header. Network as Code backend will send it to the informednotification_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
POSTrequests at the/notificationsURL 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.
- Check out how to create a QoD session with a notification URL.
- Get device reachability or roaming status notifications.
- Monitor a network slice with notifications.
- Our Network Intelligence product also provides congestion level notifications.
- Easily check if a SIM was swapped with Network as Code SDK and API.
- You can also confirm if a device uses the phone number provided by the user with the Number Verification API.
Last updated September 18, 2026