Events API

The Events API provides access to audit logs and activity events in your NetBird network, enabling compliance, monitoring, and security analysis.

Audit Events

Audit events track administrative actions and system changes.

List All Audit Events

GET /api/events/audit

curl -X GET https://api.netbird.io/api/events/audit \
  -H "Authorization: Token nbp_YOUR_TOKEN"

[
  {
    "id": "10",
    "timestamp": "2023-05-05T10:04:37.473542Z",
    "activity": "Route created",
    "activity_code": "route.add",
    "initiator_id": "google-oauth2|123456789012345678901",
    "initiator_name": "John Doe",
    "initiator_email": "demo@netbird.io",
    "target_id": "chad9d86lnnc59g18ou0",
    "meta": {
      "name": "my route",
      "network_range": "10.64.0.0/24",
      "peer_id": "chacbco6lnnbn6cg5s91"
    }
  }
]

string

Unique event identifier

string

When the event occurred (ISO 8601 format)

string

Human-readable description of the activity

string

Machine-readable activity code

string

ID of the user who triggered the event

string

Name of the user who triggered the event

string

Email of the user who triggered the event

string

ID of the resource affected by the event

object

Additional event metadata

Activity Codes

Events are categorized by activity codes for easy filtering and monitoring.

User Events

user.join
user.invite
user.create
user.delete
user.block
user.unblock
user.role.update
user.approve
user.reject
user.peer.login
user.password.change

user.invite.link.create
user.invite.link.accept
user.invite.link.regenerate
user.invite.link.delete

Peer Events

peer.user.add
peer.setupkey.add
peer.group.add
peer.group.delete
user.peer.delete
peer.rename
peer.ip.update

peer.ssh.enable
peer.ssh.disable
peer.login.expiration.enable
peer.login.expiration.disable
peer.inactivity.expiration.enable
peer.inactivity.expiration.disable
peer.login.expire

peer.approve
peer.approval.revoke

peer.job.create

Policy & Rule Events

policy.add
policy.update
policy.delete
rule.add
rule.update
rule.delete
posture.check.create
posture.check.update
posture.check.delete

Network Events

route.add
route.update
route.delete

group.add
group.update
group.delete
user.group.add
user.group.delete
setupkey.group.add
setupkey.group.delete
resource.group.add
resource.group.delete

network.create
network.update
network.delete
network.resource.create
network.resource.update
network.resource.delete
network.router.create
network.router.update
network.router.delete

DNS Events

nameserver.group.add
nameserver.group.update
nameserver.group.delete
dns.setting.disabled.management.group.add
dns.setting.disabled.management.group.delete

dns.zone.create
dns.zone.update
dns.zone.delete
dns.zone.record.create
dns.zone.record.update
dns.zone.record.delete

Setup Key Events

setupkey.add
setupkey.update
setupkey.revoke
setupkey.overuse
setupkey.delete

Token Events

personal.access.token.create
personal.access.token.delete

Account Events

account.create
account.delete
dashboard.login
transferred.owner.role

account.setting.peer.login.expiration.update
account.setting.peer.login.expiration.enable
account.setting.peer.login.expiration.disable
account.peer.inactivity.expiration.enable
account.peer.inactivity.expiration.disable
account.peer.inactivity.expiration.update
account.setting.peer.approval.enable
account.setting.peer.approval.disable
account.setting.group.propagation.enable
account.setting.group.propagation.disable
account.setting.routing.peer.dns.resolution.enable
account.setting.routing.peer.dns.resolution.disable
account.setting.lazy.connection.enable
account.setting.lazy.connection.disable
account.dns.domain.update
account.network.range.update
account.settings.auto.version.update

Integration Events

integration.create
integration.update
integration.delete
identityprovider.create
identityprovider.update
identityprovider.delete
service.create
service.update
service.delete

Network Traffic Events

Network traffic events are a Cloud-only experimental feature that tracks network flows between peers.

List Network Traffic Events

GET /api/events/network-traffic

integer

default:"1"

Page number

integer

default:"1000"

Items per page (max 50000)

string

Filter by user ID

string

Filter by reporter (peer) ID

integer

Filter by protocol (1=ICMP, 6=TCP, 17=UDP)

string

Filter by event type: TYPE_START, TYPE_END, TYPE_DROP

string

Filter by connection: P2P or ROUTED

string

Filter by direction: INGRESS, EGRESS

string

Search user email, source/destination names and addresses

string

Start date filter (ISO 8601)

string

End date filter (ISO 8601)

curl -X GET "https://api.netbird.io/api/events/network-traffic?page=1&page_size=100" \
  -H "Authorization: Token nbp_YOUR_TOKEN"

{
  "data": [
    {
      "flow_id": "61092452-b17c-4b14-b7cf-a2158c549826",
      "reporter_id": "ch8i4ug6lnn4g9hqv7m0",
      "source": {
        "id": "peer_123",
        "type": "PEER",
        "name": "laptop-01",
        "address": "100.64.0.10:51820",
        "geo_location": {
          "city_name": "Berlin",
          "country_code": "DE"
        }
      },
      "destination": {
        "id": "peer_456",
        "type": "PEER",
        "name": "server-01",
        "address": "100.64.0.15:443"
      },
      "user": {
        "id": "google-oauth2|123456",
        "email": "alice@netbird.io",
        "name": "Alice Smith"
      },
      "policy": {
        "id": "policy_789",
        "name": "Allow HTTPS"
      },
      "protocol": 6,
      "direction": "EGRESS",
      "rx_bytes": 1234,
      "rx_packets": 5,
      "tx_bytes": 1234,
      "tx_packets": 5,
      "events": [
        {
          "type": "TYPE_START",
          "timestamp": "2025-03-20T16:23:58.125397Z"
        }
      ]
    }
  ],
  "page": 1,
  "page_size": 100,
  "total_records": 523,
  "total_pages": 6
}

Reverse Proxy Access Logs

View access logs for reverse proxy services (NetBird Cloud feature).

List Proxy Access Logs

GET /api/events/proxy

integer

default:"1"

Page number

integer

default:"50"

Items per page (max 100)

string

default:"timestamp"

Field to sort by: timestamp, url, host, path, method, status_code, duration, source_ip, user_id, auth_method, reason

string

default:"desc"

Sort order: asc or desc

string

General search across fields

string

Filter by host header

string

Filter by HTTP method

integer

Filter by HTTP status code

string

Start date filter (RFC3339 format)

string

End date filter (RFC3339 format)

Example

curl -X GET "https://api.netbird.io/api/events/proxy?page=1&page_size=50" \
  -H "Authorization: Token nbp_YOUR_TOKEN"

Event Monitoring Strategies

Security Monitoring

Monitor security-relevant events:

# Watch for user account changes
activity_code: user.role.update
activity_code: user.block
activity_code: user.create

# Watch for policy changes
activity_code: policy.delete
activity_code: rule.update

# Watch for setup key usage
activity_code: setupkey.overuse
activity_code: peer.setupkey.add

Compliance Auditing

Track administrative actions:

# Configuration changes
activity_code: account.setting.*
activity_code: network.*
activity_code: route.*

# Access control changes
activity_code: policy.*
activity_code: group.*

Operational Monitoring

Monitor network health:

# Peer connectivity
activity_code: peer.user.add
activity_code: user.peer.delete
activity_code: peer.login.expire

# DNS changes
activity_code: dns.zone.*
activity_code: nameserver.group.*

Integration Examples

SIEM Integration

Forward events to your SIEM:

import requests
import time

def fetch_events():
    response = requests.get(
        "https://api.netbird.io/api/events/audit",
        headers={"Authorization": f"Token {token}"}
    )
    return response.json()

# Poll for new events every minute
while True:
    events = fetch_events()
    for event in events:
        send_to_siem(event)
    time.sleep(60)

Webhook Notifications

Send critical events to Slack/Discord:

def check_critical_events(events):
    critical_codes = [
        "user.role.update",
        "policy.delete",
        "account.delete"
    ]
    
    for event in events:
        if event["activity_code"] in critical_codes:
            notify_team(event)

Best Practices

Regular audits - Review audit logs regularly for suspicious activity

Alert on critical events - Set up monitoring for security-relevant changes

Retain logs - Export and archive events for compliance requirements

Filter effectively - Use activity codes to focus on relevant events

Monitor anomalies - Watch for unusual patterns in event data

Getting Started

Resources

Audit Events

List All Audit Events

Activity Codes

User Events

Peer Events

Policy & Rule Events

Network Events

DNS Events

Setup Key Events

Token Events

Account Events

Integration Events

Network Traffic Events

List Network Traffic Events

Reverse Proxy Access Logs

List Proxy Access Logs

Event Monitoring Strategies

Security Monitoring

Compliance Auditing

Operational Monitoring

Integration Examples

SIEM Integration

Webhook Notifications

Best Practices

​Audit Events

​List All Audit Events

​Activity Codes

​User Events

​Peer Events

​Policy & Rule Events

​Network Events

​DNS Events

​Setup Key Events

​Token Events

​Account Events

​Integration Events

​Network Traffic Events

​List Network Traffic Events

​Reverse Proxy Access Logs

​List Proxy Access Logs

​Event Monitoring Strategies

​Security Monitoring

​Compliance Auditing

​Operational Monitoring

​Integration Examples

​SIEM Integration

​Webhook Notifications

​Best Practices

Audit Events

List All Audit Events

Activity Codes

User Events

Peer Events

Policy & Rule Events

Network Events

DNS Events

Setup Key Events

Token Events

Account Events

Integration Events

Network Traffic Events

List Network Traffic Events

Reverse Proxy Access Logs

List Proxy Access Logs

Event Monitoring Strategies

Security Monitoring

Compliance Auditing

Operational Monitoring

Integration Examples

SIEM Integration

Webhook Notifications

Best Practices