API d’ingestion et webhooks d’alerte

Envoyez vos relevés à ProbeHarbor via l’API d’ingestion (JSON natif, SenML ou REST Home Assistant) et vos alertes vers Discord, IFTTT ou Home Assistant.

Gros plan de câbles Ethernet Cat-5e blancs avec connecteurs RJ45
Le JSON des sondes quitte généralement le LAN par Ethernet ou via un relais proche, pas directement par Internet. Photo : DiscDepotDundee.co.uk. CC BY-SA 4.0

En plus de récupérer des flux JSON en HTTPS, ProbeHarbor accepte l’ingestion push depuis des appareils ESP32, Pico W ou Arduino et peut diffuser les notifications d’alerte vers Discord, les SMS, les notifications push web et des webhooks HTTPS génériques pour IFTTT ou Home Assistant. Pour un résumé des endpoints et le téléchargement de l’OpenAPI, consultez la référence de l’API HTTP.

Ingestion push

Dans Dashboard → Devices, créez un appareil push et copiez la clé d’ingestion depuis l’encadré (30 minutes, survit à un rechargement). Les capteurs s’importent automatiquement au premier POST ; le mappage manuel sous Advanced est facultatif. Guide complet : Ajouter des appareils push et pull. Envoyez les mesures avec :

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

JSON Arduino classique

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

Charge utile multicapteur typée

{
  "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
}

Types pris en charge : temperature, humidity, co2, pressure, pm25, voc, level, energy, door, power, flood, motion, generic. Les champs facultatifs de premier niveau battery / battery_pct et rssi mettent à jour les métadonnées d’état de l’appareil. Des sketches d’exemple en CircuitPython, MicroPython, Arduino, Zephyr C, WCHNET C et assembleur GNU AVR pour DS18B20 / MAX31855 / MAX6675, ainsi que Uno + W5100 (ethernet_dht22_ingest, JSON temp classique) : sketches/. Le shield Ethernet ne gère pas le TLS : associez-le à push_https_forward.py sur une machine du LAN.

SenML (RFC 8428)

Si votre firmware ou votre passerelle publie déjà du JSON SenML, envoyez directement le tableau en POST, sans objet englobant. ProbeHarbor détecte automatiquement le SenML en l’absence des formes natives temp / sensors[]. La température utilise l’unité Cel ou degF ; l’humidité, %RH. Les clés de sonde proviennent du nom SenML (dernier segment du chemin).

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

Exemple en direct : flux SenML d’exemple. Les flux pull acceptent le même tableau quand la racine JSON configurée est absente.

JSON de capteur REST Home Assistant

Une réponse de capteur REST unique (state plus attributes.unit_of_measurement) est elle aussi détectée automatiquement en ingestion push et dans les flux pull. Mappez la clé de sonde state (ou le suffixe d’entité pour les charges utiles à plusieurs entités) dans Devices.

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

Exemple en direct : flux HA REST d’exemple. Pour une configuration HA complète (HACS, pont MQTT, référence intérieure), voir l’intégration Home Assistant.

Webhooks d’alerte sortants

Les comptes Pro peuvent activer un webhook sortant dans les réglages des alertes. Chaque alerte envoie ce JSON en POST :

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

kind peut valoir threshold, rate, outage, forecast, rule, digest ou generic. Quand un secret de webhook est défini, la requête inclut X-Signature, un HMAC-SHA256 hexadécimal du corps brut. Utilisez-le dans Home Assistant ou IFTTT Webhooks pour vérifier l’authenticité.

Home Assistant

Installez l’intégration HACS officielle pour disposer de capteurs issus des liens de partage et des services de mise en sourdine/vacances. Pour recevoir les alertes dans HA, utilisez le webhook HTTPS sortant (Pro) ou importez le blueprint. Pour envoyer des mesures MQTT vers ProbeHarbor, voir la recette du pont MQTT.

Télécharger le blueprint 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 }}"

Faites pointer l’URL du webhook sortant ProbeHarbor vers https://<your-ha-host>/api/webhook/probeharbor_alerts (ou une URL Cloudflare Tunnel / Nabu Casa). Vérifiez X-Signature dans une condition de modèle si vous avez défini un secret.

Pour MQTT, laissez Home Assistant (ou Node-RED) recevoir le webhook et publier sur votre broker : MQTT reste local tandis que ProbeHarbor reste en HTTPS. Le blueprint comprend une entrée facultative de topic MQTT pour ce cas.

Métriques Grafana / Prometheus

Les comptes Pro peuvent créer des clés d’API du tableau de bord (Dashboard → Share) et collecter :

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

Ou utiliser un lien de partage Pro avec la portée Metrics :

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

Ou ?format=grafana pour un simple tableau JSON de points de données. La portée de partage Historique affiche un graphique sur 7 jours sur la page publique.

Canaux d’alerte

  • E-mail et Discord (toutes les offres)
  • Jeton de bot Telegram + chat id (vos identifiants)
  • URL d’Incoming Webhook Slack (vos identifiants)
  • Push navigateur et Android (toutes les offres)
  • SMS Twilio, webhook sortant (Pro)

Les alertes prennent aussi en charge le risque de gel prévu, les heures de silence et les règles composées en ET (par exemple porte ouverte + baisse de température). Voir Dashboard → Alerts.

Les alertes par e-mail restent disponibles sur toutes les offres. Les récapitulatifs hebdomadaires s’activent indépendamment des alertes de seuil de gel/d’humidité. Les agrégats par ville (sur consentement) apparaissent sur /freeze-map.

Guides associés

FAQ

L’Arduino a-t-il besoin d’une IP publique ?
Non. L’ingestion push envoie les données en sortie vers ProbeHarbor avec une clé d’appareil. Les flux pull nécessitent une URL JSON HTTPS accessible si vous choisissez cette voie.

Que doit contenir un payload d’ingestion ?
La température (et l’humidité) indexées par sonde, plus des champs facultatifs de porte/alimentation, de batterie et de RSSI. Les formats natifs sont des clés à plat, un objet temp ou sensors[]. Les tableaux SenML (RFC 8428) et le JSON d’état REST de Home Assistant sont aussi détectés automatiquement. Gardez des clés stables pour que les associations du tableau de bord restent valides.