API de ingestão e webhooks de alerta

Envie leituras ao ProbeHarbor pela API de ingestão (JSON nativo, SenML ou Home Assistant REST) e mande alertas para Discord, IFTTT ou Home Assistant.

Close de cabos Ethernet Cat-5e brancos com conectores RJ45
O JSON das sondas normalmente sai da rede local por Ethernet ou por um relay próximo, não direto pela internet pública. Foto: DiscDepotDundee.co.uk. CC BY-SA 4.0

Além de buscar feeds JSON via HTTPS, o ProbeHarbor aceita ingestão push de dispositivos ESP32, Pico W ou Arduino e pode distribuir as notificações de alerta para Discord, SMS, push web e webhooks HTTPS genéricos para IFTTT ou Home Assistant. Para um resumo dos endpoints e o download do OpenAPI, veja a referência da API HTTP.

Ingestão push

Em Dashboard → Devices, crie um dispositivo push e copie a chave de ingestão do aviso (30 minutos; sobrevive a uma atualização da página). Os sensores são importados automaticamente no primeiro POST; o mapeamento manual em Advanced é opcional. Passo a passo completo: Adicionar dispositivos push e pull. Envie as leituras com:

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

JSON clássico do Arduino

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

Payload multissensor tipado

{
  "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 aceitos: temperature, humidity, co2, pressure, pm25, voc, level, energy, door, power, flood, motion, generic. Os campos opcionais de primeiro nível battery / battery_pct e rssi atualizam os metadados de saúde do dispositivo. Sketches de exemplo em CircuitPython, MicroPython, Arduino, Zephyr C, WCHNET C e assembly GNU AVR para DS18B20 / MAX31855 / MAX6675, além de Uno + W5100 (ethernet_dht22_ingest, JSON temp clássico): sketches/. O shield Ethernet não faz TLS: use-o junto com push_https_forward.py num computador da rede local.

SenML (RFC 8428)

Se o seu firmware ou gateway já publica JSON SenML, envie o array direto via POST, sem objeto envolvendo. O ProbeHarbor detecta SenML automaticamente quando os formatos nativos temp / sensors[] não estão presentes. A temperatura usa a unidade Cel ou degF; a umidade, %RH. As chaves de sonda vêm do nome SenML (último segmento do caminho).

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

Exemplo ao vivo: feed SenML de exemplo. Os feeds pull aceitam o mesmo array quando a raiz JSON configurada não existe.

JSON de sensor REST do Home Assistant

A resposta de um único sensor REST (state mais attributes.unit_of_measurement) também é detectada automaticamente na ingestão push e nos feeds pull. Mapeie a chave de sonda state (ou o sufixo da entidade em payloads com várias entidades) em Devices.

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

Exemplo ao vivo: feed HA REST de exemplo. Para a configuração completa do HA (HACS, ponte MQTT, referência interna), veja a integração com o Home Assistant.

Webhooks de alerta de saída

Contas Pro podem ativar um webhook de saída nas configurações de alerta. Cada alerta envia este JSON via POST:

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

kind pode ser threshold, rate, outage, forecast, rule, digest ou generic. Quando um segredo de webhook é definido, a requisição inclui X-Signature, um HMAC-SHA256 em hexadecimal do corpo bruto. Use-o no Home Assistant ou no IFTTT Webhooks para verificar a autenticidade.

Home Assistant

Instale a integração oficial do HACS para ter sensores de links compartilhados e serviços de soneca/férias. Para receber alertas no HA, use o webhook HTTPS de saída (Pro) ou importe o blueprint. Para enviar leituras MQTT ao ProbeHarbor, veja a receita da ponte MQTT.

Baixar o blueprint do 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 }}"

Aponte a URL do webhook de saída do ProbeHarbor para https://<your-ha-host>/api/webhook/probeharbor_alerts (ou uma URL do Cloudflare Tunnel / Nabu Casa). Verifique X-Signature numa condição de template se tiver definido um segredo.

Para MQTT, deixe o Home Assistant (ou o Node-RED) receber o webhook e publicar no seu broker: assim o MQTT fica local enquanto o ProbeHarbor continua em HTTPS. O blueprint inclui uma entrada opcional de tópico MQTT para esse caminho.

Métricas do Grafana / Prometheus

Contas Pro podem criar chaves de API do painel (Dashboard → Share) e coletar:

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

Ou usar um link de compartilhamento Pro com o escopo Metrics:

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

Ou ?format=grafana para um array JSON simples de pontos de dados. O escopo de compartilhamento de histórico mostra um gráfico de 7 dias na página pública.

Canais de alerta

  • E-mail e Discord (todos os planos)
  • Token de bot + chat id do Telegram (suas credenciais)
  • URL de Incoming Webhook do Slack (suas credenciais)
  • Push no navegador e no Android (todos os planos)
  • SMS via Twilio, webhook de saída (Pro)

Os alertas também aceitam risco de congelamento pela previsão, horários de silêncio e regras compostas com E (por exemplo, porta aberta + queda de temperatura). Veja Dashboard → Alerts.

Os alertas por e-mail continuam disponíveis em todos os planos. Os resumos semanais podem ser ativados independentemente dos alertas de limite de congelamento/umidade. Os dados agregados por cidade (opcionais) aparecem em /freeze-map.

Guias relacionados

Perguntas frequentes

Preciso de um IP público no Arduino?
Não. A ingestão push envia para o ProbeHarbor em conexão de saída, com uma chave de dispositivo. Feeds pull precisam de uma URL JSON HTTPS acessível se você usar esse caminho.

O que vai em um payload de ingestão?
Temperatura (e umidade) por índice de sonda, mais campos opcionais de porta/energia, bateria e RSSI. Os formatos nativos são chaves planas, um objeto temp ou sensors[]. Arrays SenML (RFC 8428) e o JSON de estado REST do Home Assistant também são detectados automaticamente. Mantenha as chaves estáveis para que os mapeamentos do painel continuem válidos.