Skip to main content
Integrate Aurora with Netdata Cloud to receive infrastructure alerts, monitor system metrics, and perform automated root cause analysis on performance issues.

​
Authentication

Netdata uses API Token authentication for Netdata Cloud.

​
Prerequisites

  • Netdata Cloud account
  • Access to at least one Netdata Space

​
Setup Steps

1

Create API Token

  1. Go to Netdata Cloud
  2. Click your avatar and select Account Settings
  3. Navigate to API Tokens
  4. Click Create Token
  5. Name: Aurora
  6. Copy the generated token (you won’t see it again)
2

Enable Netdata in Aurora

Add to your .env file:
.env
NEXT_PUBLIC_ENABLE_NETDATA=true
Restart Aurora:
make down && make dev
3

Connect to Aurora

  1. In Aurora, navigate to Integrations > Netdata
  2. Enter your API token
  3. (Optional) Enter your Space name
  4. Click Connect

​
Configuration

​
Environment Variables

.env
# Required: Enable Netdata integration
NEXT_PUBLIC_ENABLE_NETDATA=true

# For local webhook development
NGROK_URL=https://your-ngrok-url.ngrok-free.app
The Netdata integration will not appear in Aurora unless NEXT_PUBLIC_ENABLE_NETDATA=true is set.

​
Webhook Setup

Receive real-time alerts from Netdata Cloud:

​
Local Development Setup

1

Start Port Forwarding

Netdata webhooks cannot reach localhost:5080 directly. Use ngrok:
ngrok http 5080
Copy the HTTPS URL and add to .env:
.env
NGROK_URL=https://abc123.ngrok-free.app
2

Get Webhook URL

In Aurora’s Netdata integration page, copy your webhook URL:
https://abc123.ngrok-free.app/netdata/alerts/webhook/{user_id}
3

Configure in Netdata Cloud

  1. Go to Netdata Cloud
  2. Select your Space
  3. Go to Space settings > Alert notifications
  4. Click Add configuration
  5. Method: Webhook
  6. URL: Paste your Aurora webhook URL
  7. Save the configuration
4

Test the Webhook

Send a test notification from Netdata Cloud to verify connectivity. Aurora will store the verification token automatically.

​
Production Setup

In production, webhooks use your production backend URL automatically. Webhook URL format: 
https://your-aurora-domain/netdata/alerts/webhook/{user_id}

​
What Aurora Can Query

Once connected, Aurora can:

​
Connection Status

  • Verify API token is valid
  • Check Space configuration
  • View base URL
API Endpoint: GET /netdata/status Response: 
{
  "connected": true,
  "baseUrl": "https://app.netdata.cloud",
  "spaceName": "Production Infrastructure"
}

​
Webhook Alerts

  • Receive real-time alerts from Netdata agents
  • Auto-create incidents from critical alerts
  • Track alert status transitions
  • Correlate alerts across nodes
  • Generate AI-powered root cause analysis
Ingested Data:
  • Alert name and status (WARNING, CRITICAL, CLEAR)
  • Chart and metric information
  • Host and node details
  • Space and room context
  • Alert value and thresholds
  • Alert message and description
API Endpoint: GET /netdata/alerts Parameters:
  • limit - Number of alerts (default: 50)
  • offset - Pagination offset (default: 0)
  • status - Filter by status (WARNING, CRITICAL, CLEAR)
Response: 
{
  "alerts": [
    {
      "id": 123,
      "alertName": "system.cpu.user",
      "status": "CRITICAL",
      "chart": "system.cpu",
      "host": "prod-server-01",
      "space": "Production",
      "room": "Web Servers",
      "value": "95.5",
      "message": "High CPU usage detected",
      "receivedAt": "2026-03-03T10:30:00Z",
      "payload": {...}
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

​
Webhook Verification

  • Get webhook verification token
  • Required by Netdata for webhook authentication
  • Token is automatically stored when test notification is sent
API Endpoint: GET /netdata/alerts/webhook-url Response: 
{
  "webhookUrl": "https://your-aurora-domain/netdata/alerts/webhook/{user_id}",
  "verificationToken": "abc123def456..."
}
The verification token is automatically extracted and stored when Netdata sends a test notification. You don’t need to manually configure it.

​
Troubleshooting

“Netdata connector not enabled”
  • Ensure NEXT_PUBLIC_ENABLE_NETDATA=true is set in .env
  • Restart Aurora services with make down && make dev
  • Check that the environment variable is loaded correctly
Connection Failed
  • Verify API token is correct and not expired
  • Check that token was created in Netdata Cloud (not a local agent)
  • Ensure you have access to at least one Space
Webhook Not Receiving Alerts
  • Verify NGROK_URL is set correctly (local development)
  • Ensure ngrok tunnel is running
  • Check webhook URL in Netdata matches Aurora UI
  • Send test notification from Netdata Cloud
  • Verify alert notification rules are configured in your Space
Missing Verification Token
  • Send a test notification from Netdata Cloud webhook settings
  • Aurora will automatically extract and store the token
  • Refresh the Aurora Netdata integration page to see the token
Alerts Not Creating Incidents
  • Check Aurora logs for webhook processing errors
  • Verify alert payload contains required fields (alert name, status)
  • Ensure incident creation is enabled in Aurora settings

​
API Reference

Base Path: /netdata
MethodEndpointDescription
POST/connectConnect Netdata account
GET/statusCheck connection status
DELETE/disconnectRemove Netdata connection
GET/alertsList webhook alerts
POST/alerts/webhook/{user_id}Receive webhooks
GET/alerts/webhook-urlGet webhook URL and token
For detailed Netdata documentation, see:

Build docs developers (and LLMs) love

Get started for freeTalk to us