Home Assistant Integration

Overview

Home Assistant ships a built-in rest sensor platform. We'll define a sensor whose value is the threat score for an IP that you set via an input helper, and a small automation that fires a critical mobile notification when the score crosses a threshold — ideal for "someone just hit my Nginx Proxy Manager from a known-bad IP" alerting.

Prerequisites

Home Assistant 2024.1+ (any installation method)
An ipinsights.io API key — your profile page
Optional but recommended: a secrets-store entry for the key

Step 1 — Store the API Key

Add the key to secrets.yaml so it never lands in configuration.yaml:

# secrets.yaml
ipinsights_api_key: "your-api-key-here"

Step 2 — Input Helper

Add an input text helper so the IP you want to look up can be set from automations / the UI. Inside configuration.yaml:

input_text:
  ipinsights_target_ip:
    name: IP Insights — IP to check
    initial: "8.8.8.8"
    max: 45

Step 3 — REST Sensor

rest:
  - resource_template: "https://ipinsights.io/api/v1/lookup?ip={{ states('input_text.ipinsights_target_ip') }}"
    headers:
      X-API-Key: !secret ipinsights_api_key
      Accept: application/json
    scan_interval: 900            # every 15 minutes
    sensor:
      - name: "IP Insights Threat Score"
        unique_id: ipinsights_threat_score
        value_template: "{{ value_json.data.threat_score | int(0) }}"
        unit_of_measurement: "score"
        icon: mdi:shield-alert
        json_attributes_path: "$.data"
        json_attributes:
          - country_code
          - asn
          - isp
          - is_tor
          - is_vpn
          - is_proxy
          - blocklist_count
      - name: "IP Insights Country"
        unique_id: ipinsights_country
        value_template: "{{ value_json.data.country_code }}"
        icon: mdi:earth

Restart Home Assistant (or use Developer Tools → YAML → Reload REST) to load the sensor.

Step 4 — Automation

Example automation: whenever Nginx Proxy Manager (or any source you trust to publish a last_remote_ip sensor) reports a new IP, set the input helper and notify on a high score. Adapt the trigger to wherever the IP comes from on your network.

automation:
  - alias: "Notify on risky inbound IP"
    trigger:
      - platform: state
        entity_id: sensor.npm_last_client_ip
    action:
      - service: input_text.set_value
        target:
          entity_id: input_text.ipinsights_target_ip
        data:
          value: "{{ trigger.to_state.state }}"
      - delay: "00:00:05"               # give the REST sensor time to update
      - condition: numeric_state
        entity_id: sensor.ip_insights_threat_score
        above: 70
      - service: notify.mobile_app
        data:
          title: "⚠️ Risky IP hitting your homelab"
          message: >-
            {{ trigger.to_state.state }} —
            score {{ states('sensor.ip_insights_threat_score') }}
            ({{ state_attr('sensor.ip_insights_threat_score','country_code') }},
            ASN {{ state_attr('sensor.ip_insights_threat_score','asn') }})
          data:
            push:
              interruption-level: critical

Verify

Developer Tools → States → find sensor.ip_insights_threat_score and confirm the attributes are populated.
Set input_text.ipinsights_target_ip to a Tor exit node and confirm the score jumps and is_tor flips to true.
Manually trigger the automation from the UI to make sure your mobile notification fires.

API Key: Required — store it in secrets.yaml. Find your key on your profile page.

Request Higher API Limit

Running a high-volume Home Assistant deployment? If the default rate limit isn't enough for your environment, submit a request below and we'll review it.

Your Name *

Email Address *

Company / Organisation

Current Limit *

Requested Limit *

Use Case * Maximum 5,000 characters.