Event Streams

Event Streams is a NetBox Cloud feature that publishes real-time events to cloud messaging services when objects in NetBox are created, updated, or deleted. You can subscribe to these events to trigger automations, feed SIEM platforms, or integrate with other systems in your environment.

Supported services

Event types

Event Streams publishes the following event types:

Getting started

Event Streams is provisioned and managed by NetBox Labs. To set up Event Streams for your NetBox Cloud instance:

1. Contact NetBox Labs Support with your requirements
2. Specify your preferred messaging service (AWS SNS or Azure Service Bus)
3. NetBox Labs provisions the integration and provides you with connection details

Once provisioned, consume events from the messaging service using the connection details provided.

Architecture

NetBox Cloud Instance
    ↓
Event Processing
    ↓
Rule Matching & Routing
    ├→ AWS SNS Topic
    └→ Azure Service Bus Topic
        ↓
Your External Systems

Message format

Event Streams delivers messages in a standardized envelope format:

{
  "version": 1,
  "source_id": "550e8400-e29b-41d4-a716-446655440000",
  "source_timestamp": "2025-10-29T10:30:00.000000Z",
  "source_type": "object_created",
  "source_type_docs": "https://docs.netboxlabs.com/event-streams/#event-types",
  "netbox_id": "nb-abc123",
  "netbox_version": "4.1.0",
  "egress_environment": "production",
  "egress_id": "660e8400-e29b-41d4-a716-446655440001",
  "egress_timestamp": "2025-10-29T10:30:00.123456Z",
  "egress_version": "2.3.1",
  "message": {
    "event": "created",
    "model": "dcim.device",
    "username": "admin",
    "data": { ... }
  }
}

Key fields:

• source_id - Unique ID for the originating event
• source_timestamp - When the event occurred in NetBox
• source_type - The event type (see Event types)
• netbox_id - Identifier for the NetBox Cloud instance
• egress_id - Unique ID for the message delivery
• egress_timestamp - When the event was delivered to the messaging service
• message - The NetBox event payload, including the object data and the user who made the change

Use cases

Trigger automations - When a new device is added in NetBox, Event Streams can kick off configuration pipelines, update monitoring systems, or initiate vulnerability scans.

Feed SIEM platforms - Stream network state changes and security audit events (such as failed login attempts) into Splunk Enterprise, ElasticSearch, or other SIEM tools for real-time security logging and analysis.

Synchronize monitoring - Keep observability platforms in sync with infrastructure changes by reacting to device, interface, or IP address updates as they happen.

Automated device onboarding - Trigger configuration deployment and security system notifications simultaneously when new devices are provisioned, ensuring proper setup and immediate visibility.

Best practices

• Message deduplication - Use egress_id to detect and handle duplicate deliveries
• Error handling - Implement dead-letter queues for failed message processing
• Batch processing - Process multiple events together when possible for efficiency
• Monitoring - Set up alerting on message queue depth and processing latency
• Schema validation - Validate message structure before processing

Heartbeats

Event Streams can send a heartbeat message once a minute alongside your object change events. Heartbeats take the same path from NetBox to your messaging service as every other event, so a steady heartbeat confirms the stream is working even when nothing in NetBox has changed. If heartbeats stop arriving, the stream has stopped delivering.

Heartbeats are off by default. To turn them on for your instance, contact NetBox Labs Support.

Heartbeat message format

Heartbeats use the same envelope as other events, with source_type set to heartbeat_event:

{
  "version": 1,
  "source_id": "8f2a6d14-5c3b-4a97-b0e2-71d9c4f8a6b5",
  "source_timestamp": "2026-10-16T10:16:00.412000Z",
  "source_type": "heartbeat_event",
  "source_type_docs": "https://docs.netboxlabs.com/event-streams/#event-types",
  "netbox_id": "nb-abc123",
  "netbox_version": "4.7.2",
  "egress_environment": "production",
  "egress_id": "2c41b7e9-0d5a-4f38-9e16-b8a3c7d2f590",
  "egress_timestamp": "2026-10-16T10:16:00.412311Z",
  "egress_version": "2.3.1",
  "message": {
    "event": "heartbeat_event",
    "timestamp": "2026-10-16T10:16:00.083417+00:00",
    "sequence": 1442,
    "scheduled": "2026-10-16T10:16:00.004812+00:00"
  }
}

Heartbeat fields in message:

• timestamp - When NetBox sent the heartbeat (ISO 8601)
• scheduled - When the heartbeat was due to be sent (ISO 8601). This is null for the first heartbeat after NetBox restarts its background workers, which is sent straight away.
• sequence - A number that increases by one with each heartbeat. It can restart from a lower number after NetBox Labs maintenance, so treat a drop as a reset, not as a gap.

Monitoring with heartbeats

• Detect a stalled stream - Alert when no heartbeat has arrived for a few minutes. This is the most reliable check: if NetBox stops sending heartbeats altogether, there's no message to inspect, only an absence.
• Detect lost messages - A jump in sequence between consecutive heartbeats means heartbeats were lost between NetBox and your consumer. Other events on the same path may have been lost too.
• Measure delivery latency - Compare the time a heartbeat arrives with its scheduled time (or timestamp, when scheduled is null) to track how long events take to reach you.

Filtering heartbeats

Heartbeats arrive on the same topic as your object change events, about 1,440 per day per NetBox instance. Consumers that act on object changes should skip messages where source_type is heartbeat_event.

Troubleshooting

Delivery failures

Check:

• Messaging service configuration is correct
• IAM permissions allow publishing to the topic
• Topic ARN or name exists in the cloud provider
• Network connectivity to cloud provider APIs
• Message size is within provider limits

Debug:

• Review delivery logs in CloudWatch (AWS) or Azure Monitor
• Verify message format matches expected schema
• Contact NetBox Labs Support if delivery issues persist

Code example: AWS Lambda consumer

import json

def lambda_handler(event, context):
    """Process NetBox events from SNS"""

    for record in event['Records']:
        message = json.loads(record['Sns']['Message'])

        netbox_event = message['message']
        event_type = message['source_type']
        netbox_id = message['netbox_id']

        print(f"Processing {event_type} from {netbox_id}")

        if event_type == 'object_created':
            handle_object_created(netbox_event)
        elif event_type == 'object_updated':
            handle_object_updated(netbox_event)
        elif event_type == 'object_deleted':
            handle_object_deleted(netbox_event)

    return {'statusCode': 200}

def handle_object_created(event):
    """Handle object creation events"""
    model = event['model']
    data = event['data']

    if model == 'dcim.device':
        device_name = data['name']
        site_name = data['site']['name']
        print(f"New device: {device_name} at {site_name}")

        update_monitoring_system(device_name, site_name)
        update_cmdb(data)

Related documentation

• NetBox Event Rules - Configure event-triggered actions (webhooks, scripts, notifications) in core NetBox
• NetBox Webhooks - Send HTTP callbacks from NetBox on object changes