API de ingesta y webhooks de alertas

Envía lecturas a ProbeHarbor con la API de ingesta (JSON nativo, SenML o REST de Home Assistant) y alertas a Discord, IFTTT o Home Assistant.

Primer plano de cables Ethernet Cat-5e blancos con conectores RJ45 — El JSON de las sondas suele salir de la LAN por Ethernet o por un relay cercano, no directamente a internet. Foto: DiscDepotDundee.co.uk. CC BY-SA 4.0

Además de extraer feeds JSON por HTTPS, ProbeHarbor acepta ingesta push desde dispositivos ESP32, Pico W o Arduino y puede repartir las notificaciones de alerta a Discord, SMS, notificaciones push web y webhooks HTTPS genéricos para IFTTT o Home Assistant. Para ver un resumen de los endpoints y descargar el OpenAPI, consulta la referencia de la API HTTP.

Ingesta push

En Dashboard → Devices, crea un dispositivo push y copia la clave de ingesta del aviso (30 minutos; sobrevive a una recarga). Los sensores se importan automáticamente con el primer POST; la asignación manual en Advanced es opcional. Guía completa: Añadir dispositivos push y pull. Envía las lecturas con:

POST /api/ingest/<device-key>
Content-Type: application/json

JSON clásico de Arduino

{
  "temp": {
    "0": { "c": 18.5, "f": 65.3, "h": 42 },
    "1": { "c": 19.0, "f": 66.2, "h": 40 }
  }
}

Payload multisensor con tipos

{
  "sensors": [
    { "key": "garage_temp", "kind": "temperature", "value": 65.3, "unit": "F" },
    { "key": "garage_rh", "kind": "humidity", "value": 42, "unit": "%" },
    { "key": "door1", "kind": "door", "bool": true },
    { "key": "co2", "kind": "co2", "value": 820, "unit": "ppm" },
    { "key": "pm25", "kind": "pm25", "value": 12, "unit": "µg/m³" },
    { "key": "sump", "kind": "level", "value": 22, "unit": "%" }
  ],
  "battery": 87,
  "rssi": -62
}

Tipos admitidos: temperature, humidity, co2, pressure, pm25, voc, level, energy, door, power, flood, motion, generic. Los campos opcionales de primer nivel battery / battery_pct y rssi actualizan los metadatos de estado del dispositivo. Sketches de ejemplo en CircuitPython, MicroPython, Arduino, Zephyr C, WCHNET C y ensamblador GNU AVR para DS18B20 / MAX31855 / MAX6675, además de Uno + W5100 (ethernet_dht22_ingest, JSON temp clásico): sketches/. El shield Ethernet no puede hacer TLS: combínalo con push_https_forward.py en un equipo de la LAN.

SenML (RFC 8428)

Si tu firmware o tu gateway ya publican JSON SenML, envía el array directamente con POST, sin objeto contenedor. ProbeHarbor detecta SenML automáticamente cuando no están presentes los formatos nativos temp / sensors[]. La temperatura usa la unidad Cel o degF; la humedad, %RH. Las claves de sonda salen del nombre SenML (último segmento de la ruta).

[
  { "bn": "probeharbor/garage/", "n": "0", "u": "Cel", "v": 18.5 },
  { "n": "0", "u": "%RH", "v": 42 },
  { "n": "door", "vb": true }
]

Ejemplo en vivo: feed SenML de ejemplo. Los feeds pull aceptan el mismo array cuando falta la raíz JSON configurada.

JSON de sensor REST de Home Assistant

Una respuesta de un único sensor REST (state más attributes.unit_of_measurement) también se detecta automáticamente en la ingesta push y en los feeds pull. Asigna la clave de sonda state (o el sufijo de la entidad en payloads con varias entidades) en Devices.

{
  "state": "65.3",
  "attributes": {
    "unit_of_measurement": "°F",
    "friendly_name": "Garage temperature"
  }
}

Ejemplo en vivo: feed HA REST de ejemplo. Para la configuración completa de HA (HACS, puente MQTT, referencia interior), consulta la integración con Home Assistant.

Webhooks de alerta salientes

Las cuentas Pro pueden activar un webhook saliente en los ajustes de alertas. Cada alerta envía este JSON por POST:

{
  "title": "Garage temperature alert",
  "body": "Probe 1 is 31.2°F …",
  "kind": "threshold",
  "sent_at": "2026-08-25T12:00:00.000Z"
}

kind puede ser threshold, rate, outage, forecast, rule, digest o generic. Si defines un secreto para el webhook, la petición incluye X-Signature, un HMAC-SHA256 en hexadecimal del cuerpo sin procesar. Úsalo en Home Assistant o en IFTTT Webhooks para verificar la autenticidad.

Home Assistant

Instala la integración oficial de HACS para tener sensores de enlaces compartidos y servicios de posponer/vacaciones. Para recibir alertas en HA, usa el webhook HTTPS saliente (Pro) o importa el blueprint. Para enviar lecturas MQTT a ProbeHarbor, consulta la receta del puente MQTT.

Descargar el blueprint de HA (YAML)

automation:
  - alias: ProbeHarbor webhook
    trigger:
      - platform: webhook
        webhook_id: probeharbor_alerts
        allowed_methods:
          - POST
        local_only: false
    action:
      - service: notify.persistent_notification
        data:
          title: "{{ trigger.json.title }}"
          message: "{{ trigger.json.body }}"

Apunta la URL del webhook saliente de ProbeHarbor a https://<your-ha-host>/api/webhook/probeharbor_alerts (o a una URL de Cloudflare Tunnel / Nabu Casa). Si defines un secreto, verifica X-Signature en una condición de plantilla.

Para MQTT, haz que Home Assistant (o Node-RED) reciba el webhook y lo publique en tu broker: así MQTT se queda en local mientras ProbeHarbor sigue en HTTPS. El blueprint incluye una entrada opcional de tema MQTT para esa opción.

Métricas de Grafana / Prometheus

Las cuentas Pro pueden crear claves de API del panel (Dashboard → Share) y hacer scraping de:

GET /api/v1/metrics
Authorization: Bearer gtm_…

O usar un enlace compartido Pro con el alcance Metrics:

GET /api/share/<token>/readings?format=prometheus

O ?format=grafana para un array JSON sencillo de puntos de datos. El alcance de historial de un enlace compartido muestra un gráfico de 7 días en la página pública.

Canales de alerta

Correo y Discord (todos los planes)
Token de bot y chat id de Telegram (tus credenciales)
URL de Incoming Webhook de Slack (tus credenciales)
Notificaciones push en el navegador y Android (todos los planes)
SMS de Twilio, webhook saliente (Pro)

Las alertas también admiten riesgo de congelación según el pronóstico, horas de silencio y reglas compuestas con AND (por ejemplo, puerta abierta + bajada de temperatura). Consulta Dashboard → Alerts.

Las alertas por correo siguen disponibles en todos los planes. Los resúmenes semanales se pueden activar con independencia de las alertas de umbral de congelación o humedad. Los datos agregados por ciudad (opcionales) aparecen en /freeze-map.

Guías relacionadas

Documentación de la API HTTP: descarga del OpenAPI, ingesta, métricas y webhooks entrantes
Alta con el QR del kit: codifica tu URL de ingesta en una pegatina para el hardware
OTA del ESP32 e informe de batería: actualizaciones de firmware y campos battery / rssi
Recetas para Zapier y Make.com: webhooks de alerta salientes y automatizaciones de posponer entrantes

Preguntas frecuentes

¿Necesito una IP pública en el Arduino?
No. La ingesta push envía datos salientes a ProbeHarbor con una clave de dispositivo. Los feeds pull necesitan una URL JSON HTTPS accesible si usas esa vía.

¿Qué debe incluir un payload de ingesta?
La temperatura (y la humedad) indexadas por sonda, más campos opcionales de puerta/alimentación, batería y RSSI. Los formatos nativos son claves planas, un objeto temp o sensors[]. También se detectan automáticamente los arrays SenML (RFC 8428) y el JSON de estado REST de Home Assistant. Mantén las claves estables para que las asignaciones del panel sigan siendo válidas.