Notifications

Access the notifications produced by the BGP monitoring, and all the services offered by PacketVis through a single API.

Getting started

1. Generate an API key (see Authentication).
2. Build the request URL. Replace YOUR_API_KEY in the examples with your API key.

List notifications

GEThttps://api.packetvis.com/v1/notifications/?key=YOUR_API_KEY

Returns the notifications produced by the BGP monitoring and by the other PacketVis services, with optional filters.

Parameters

Name	Description	Default
key	The API key.
services	A comma-separated list of service names you want to receive notifications from. See services and types.	All of them
types	A comma-separated list of notification types to retrieve (e.g., hijack events). See services and types.	All of them
severity	The minimum severity of the notifications to retrieve: 1 min, 2 med, 3 high, 4 critical.	0
warning	The amount of minutes (between 1 and 120) the warning remains active after a notification. The warning parameter allows you to integrate this API endpoint directly with third-party alerting systems.	10
status	Return HTTP 418 if there is a warning ongoing. The usual payload is sent as well. This is the same as the warning parameter, which allows you to integrate this API endpoint directly with third-party alerting systems. In this case, no JSON body parsing is required and you can use normal HTTP checks (e.g., in nagios or checkmk).	false
start	A UNIX timestamp (seconds) used as start time to filter the notifications. Optional, but if used stop must be declared as well.
stop	A UNIX timestamp (seconds) used as stop time to filter the notifications. It must be in the past. Optional, but if used start must be declared as well.

Response

200 OK

{
  "data": {
    "notifications": [
      {
        "service": "bgp",
        "type": "rpki-invalid",
        "summary": "The route XXXX announced by ASXXX is not RPKI valid.",
        "url": "https://packetvis.com/bgp/event/23ff",
        "id": "23ff",
        "dispatched": true,
        "createdAt": "2022-09-07T05:33:41.981Z",
        "severity": 4,
        "resolved": null
      }
    ],
    "warning": false
  },
  "metadata": {
    "useStatusCode": false,
    "warningMinutes": 10
  }
}

Fields of each object in data.notifications:

Field	Type	Description
service	string	The service that produced the notification. See services and types.
type	string	The notification type. See services and types.
summary	string	A short description of the event.
url	string	Link to the event on packetvis.com.
id	string | integer	The unique identifier of the notification.
dispatched	boolean	Whether the notification was dispatched to your configured channels.
createdAt	string (ISO 8601)	When the notification was created.
severity	integer	1 min, 2 med, 3 high, 4 critical.
resolved	string (ISO 8601) | null	When the event that triggered the notification was resolved. null means the event is not resolved or has no possible resolution (purely informative).

Other fields:

Field	Type	Description
data.warning	boolean	true if there was an unresolved notification within the warning window. See warning and status codes.
metadata.useStatusCode	boolean	Whether the status parameter was set.
metadata.warningMinutes	integer	The warning window, in minutes.

Services and types

Service	Types
generic	setup, test, admin, resolution
bgp	hijack, visibility, misconfiguration, bogons, path, newprefix, neighbors, rpki-invalid, rpki-unknown, ta-expire, ta-malfunction, roa-diff, roa-expire, upstreams-visibility, upstreams-availability, grouped

Warning and status codes

The warning parameter controls how long a notification keeps the warning active. For example, with warning=30 the returned JSON contains "warning": true if there was an unresolved notification in the last 30 minutes.

This makes integration with systems such as Icinga or Nagios easy: poll the API and look for warning: true, without parsing the notifications.

To avoid parsing the JSON entirely, set status=true. In addition to warning: true, the API returns an HTTP 418 status code, so your monitoring solution marks the HTTP call as failing automatically. The payload remains intact for inspection.