블로그로 돌아가기

rest_command로 보내는 Home Assistant 푸시 알림: 누수, 세탁기, 현관문

rest_command로 보내는 Home Assistant 푸시 알림: 누수, 세탁기, 현관문

Home Assistant Companion 앱은 Home Assistant를 직접 운영하는 사람에게는 알림을 잘 전해 줘요. 하지만 지하실 누수를 가장 먼저 알아야 하는 사람이 앱을 설치하지 않은 배우자, 부모님, 또는 여분의 열쇠를 맡긴 이웃이라면 불편해지죠. 푸시 한 번 받으라고 Home Assistant 계정을 만들어 주는 건 필요 이상의 권한을 주는 일이에요.

알림이 많아진다는 문제도 있어요. "세탁기 완료"와 "욕실 바닥에 물이 있음"은 같은 소리로 울리면 안 돼요. 서버 알림이 이미 다른 앱으로 오고 있다면 확인해야 할 피드가 두 개가 되어 버리고요.

이 가이드에서는 Home Assistant의 rest_command로 Pocket Alert를 통해 푸시 알림을 보내요. 애드온이나 커스텀 통합이 필요 없고, 자동화 세 가지를 다뤄요. 치명적 수준의 수도 누수, 낮음 수준의 세탁기 완료, 아무도 없는 집에서 열린 현관문이에요.

준비물

  • configuration.yaml에 접근할 수 있는 Home Assistant (File editor, Studio Code Server 애드온, 또는 SSH).
  • Pocket Alert 계정, API 키 페이지에서 발급받은 API 키, 그리고 알림을 받을 휴대폰에 설치한 앱 (iPhone 또는 Android). 무료 플랜은 기기 한 대에서 하루 50개 메시지를 보낼 수 있어요.

rest_command 설정

키를 configuration.yaml과 같은 폴더에 있는 secrets.yaml에 넣어요:

pocketalert_token: "YOUR_API_KEY"

그다음 configuration.yaml에 명령 하나를 추가해요:

rest_command:
  pocketalert:
    url: https://api.pocketalert.app/v1/messages
    method: post
    content_type: application/json
    timeout: 10
    headers:
      Token: !secret pocketalert_token
    payload: >-
      {% set body = {"title": title, "message": message,
                     "level": level | default("default")} %}
      {% if button_url is defined %}
        {% set req = {"url": button_url, "method": "POST"} | to_json %}
        {% set body = dict(body, actions=[{"type": "http",
              "label": button_label | default("Run"), "value": req}]) %}
      {% endif %}
      {{ body | to_json }}

Home Assistant을 다시 시작해요. 이제 rest_command.pocketalert라는 액션이 생기고, data에 넘긴 값이 템플릿 변수가 돼요: title, message, 선택 사항인 level, 그리고 선택 사항인 버튼이에요.

JSON을 손으로 쓰지 않고 to_json으로 만드는 이유가 있어요. 센서 이름에 따옴표가 들어 있으면 손으로 쓴 문자열은 깨지는데, to_json은 이를 자동으로 이스케이프해 줘요. Pocket Alert API는 JSON만 받아요. 그래서 content_type도 설정해 둔 거예요. 이걸 빼면 JSON 콘텐츠 타입 없이 요청이 나가요.

개발자 도구 → 액션에서 테스트해 볼 수 있어요. rest_command.pocketalert를 고르고 YAML 모드로 전환한 뒤 실행하세요:

action: rest_command.pocketalert
data:
  title: "Hello from Home Assistant"
  message: "rest_command works"

1~2초 안에 푸시가 도착해야 해요.

자동화 세 가지

자동화 편집기의 YAML로 편집에서 추가하거나 automations.yaml에 넣으세요. 엔티티 ID는 본인 것으로 바꿔 주세요.

수도 누수: 치명적

alias: "Leak under the sink"
triggers:
  - trigger: state
    entity_id: binary_sensor.kitchen_leak
    to: "on"
actions:
  - action: rest_command.pocketalert
    data:
      title: "Water leak: kitchen"
      message: "The sensor under the sink is wet. Check it now."
      level: critical

critical은 아침까지 기다릴 수 없는 일에 쓰는 수준이에요. iPhone에서는 무음 스위치와 방해 금지 모드를 무시하고 자체 볼륨으로 울려요. Android에서는 방해 금지 모드를 우회하는 별도 채널을 쓰고 화면을 가득 채워요. critical은 유료 플랜에서만 쓸 수 있어요. 무료 플랜에서는 같은 메시지가 high로 도착하는데, 이 수준은 집중 모드는 통과하지만 무음 스위치는 통과하지 못해요.

세탁기 완료: 낮음

"세탁기 완료" 센서는 따로 없어요. 대신 전력 측정이 되는 스마트 플러그로 알 수 있어요. 소비 전력이 몇 분 동안 몇 와트 아래로 유지되면 사이클이 끝난 거예요.

alias: "Washer finished"
triggers:
  - trigger: numeric_state
    entity_id: sensor.washer_plug_power
    below: 5
    for: "00:03:00"
actions:
  - action: rest_command.pocketalert
    data:
      title: "Washer finished"
      message: "Laundry is ready to hang."
      level: low

low는 소리도 없고 방해도 없이 조용히 도착해요. 휴대폰을 봤을 때 목록에 남아 있는 정도인데, 젖은 빨래는 사실 그 정도로 급하죠. 세탁기에 맞게 below와 for를 조정하세요. 어떤 세탁기는 사이클 중간에 1~2분씩 멈추기도 해요.

아무도 없을 때 열린 현관문: 높음

zone.home의 상태는 그 영역에 있는 사람 수이므로, "0"이면 모두 외출한 거예요.

alias: "Front door opened while away"
triggers:
  - trigger: state
    entity_id: binary_sensor.front_door
    to: "on"
conditions:
  - condition: state
    entity_id: zone.home
    state: "0"
actions:
  - action: rest_command.pocketalert
    data:
      title: "Front door opened"
      message: "Opened at {{ now().strftime('%H:%M') }} and nobody is home."
      level: high

high는 iPhone에서 시간 민감 알림으로 표시돼서 집중 모드와 예약 요약을 통과해요. 메시지 줄은 템플릿이에요. data의 값은 명령에 전달되기 전에 렌더링돼요.

수도 밸브를 잠그는 버튼

누수 알림은 바로 조치할 수 있을 때 더 쓸모 있어요. Pocket Alert 알림에는 최대 세 개의 액션 버튼을 넣을 수 있고, http 버튼은 휴대폰에서 직접 요청을 보내요. Pocket Alert가 중계하지 않아요. 그래서 휴대폰이 닿을 수만 있다면 인터넷에 열려 있지 않은 Home Assistant 웹훅도 버튼으로 호출할 수 있어요.

먼저 웹훅이 호출되면 밸브를 잠그는 자동화를 만들어요:

alias: "Close main water valve (from push)"
triggers:
  - trigger: webhook
    webhook_id: "close-valve-9f2c41d7a3b8e605"
    allowed_methods:
      - POST
    local_only: true
actions:
  - action: valve.close_valve
    target:
      entity_id: valve.main_water

밸브가 스위치로 나타난다면 valve.close_valve 대신 switch.turn_off를 쓰세요. 웹훅 ID는 길고 무작위로 만드세요. Home Assistant 웹훅은 ID를 아는 것 말고는 별도 인증이 없어요.

그다음 누수 자동화에 버튼을 추가해요:

actions:
  - action: rest_command.pocketalert
    data:
      title: "Water leak: kitchen"
      message: "The sensor under the sink is wet."
      level: critical
      button_label: "Close water valve"
      button_url: "https://ha.example.com/api/webhook/close-valve-9f2c41d7a3b8e605"

위의 rest_command는 button_url을 메서드가 POST인 http 액션으로 바꿔요. 버튼을 누르면 앱을 열지 않아도 휴대폰이 백그라운드에서 요청을 보내요.

어떤 URL을 쓸지는 이렇게 정하면 돼요:

  • 집에 있을 때만: Wi-Fi에서 휴대폰이 Home Assistant에 접속하는 주소예요. local_only: true로 웹훅을 인터넷에 열지 않을 수 있어요. 네트워크에 https:// 주소가 있다면 그걸 쓰는 게 좋아요.
  • 어디서든: 누수는 보통 외출 중에 생기죠. Home Assistant 문서에 따르면 local_only 웹훅도 Home Assistant Cloud(Nabu Casa) 웹훅을 통해 동작하므로, 클라우드 URL이 가장 간편한 선택이에요. Tailscale이나 WireGuard 같은 VPN을 휴대폰에 설정하면 내부망 주소로도 동작해요.

Home Assistant도 문 잠금 해제처럼 파괴적이거나 위험한 동작은 웹훅 뒤에 두지 말라고 권장해요. 수도 밸브를 잠그는 건 안전한 방향이지만, 여는 건 그렇지 않아요. 그러니 휴대폰 버튼에는 여는 동작을 넣지 마세요. 버튼을 두 번 누르면 요청이 두 번 가는데, 이미 잠긴 밸브를 한 번 더 잠그는 건 아무 일도 일으키지 않으니 괜찮아요.

버튼에 대해 알아 둘 점이 두 가지 있어요. 액션 버튼은 유료 플랜 기능이라서 무료 플랜에서는 메시지에서 빠져요. 알림 자체는 그대로 도착하고요. 그리고 iOS와 Android 모두 Pocket Alert 앱이 닫혀 있어도 알림 위에 본인이 정한 라벨이 그대로 표시돼요(버전 2.0.1 이상). 버튼은 메시지와 함께 앱에 저장되기 때문에, 배너가 사라진 뒤에도 앱에서 누를 수 있어요.

Home Assistant가 없는 사람을 위한 알림

푸시를 받는 사람은 Pocket Alert 앱만 있으면 돼요. 설정 방법은 두 가지예요:

  • 본인 계정. 무료로 가입하고 API 키를 만들어서 보내 주면 돼요. secrets.yaml에 그 사람의 키를 넣은 두 번째 명령 pocketalert_family를 추가하고, 누수 자동화에서 두 명령을 모두 호출하세요. 서버 알림은 본인 계정에 남고, 그 사람은 여러분이 보내는 것만 보게 돼요.
  • 본인 계정의 두 번째 기기. 유료 플랜에는 여러 기기가 포함돼요. 그 사람의 휴대폰을 추가한 뒤, 명령의 body 딕셔너리에 "device_id": "THEIR_DEVICE_ID"를 넣은 복사본을 만드세요. 그러면 가족에게 필요한 알림만 그 기기로 가요.

어느 쪽이든 그 사람은 Home Assistant 계정 없이도 같은 수준과 버튼이 있는 누수 알림을 받게 돼요.

집과 그 밖의 모든 것을 위한 앱 하나

같은 API 키를 크론 작업, 백업, 업타임 점검, CI에도 쓸 수 있어요. 홈랩을 운영한다면 Proxmox, NAS, 백업 알림도 누수 센서와 같은 피드로 들어와요. 각각 고유한 수준을 갖고, 앱에서 수준별로 피드를 걸러 볼 수 있어서 마흔 개 중에서 중요한 두 개를 쉽게 찾을 수 있어요. 다른 센서(ESP32 보드, 라즈베리 파이, Node-RED)는 IoT 및 센서 알림을 참고하세요.

JSON 웹훅만 보낼 수 있는 기기라면 코드 없이 쓸 수 있는 방법도 있어요. 콘솔에서 웹훅을 만들고 페이로드에서 메시지를 템플릿으로 구성하면 돼요. 자세한 내용은 웹훅을 푸시로를 보세요.

notify 액션으로 쓰는 RESTful Notifications

notify.* 액션을 선호한다면 Home Assistant의 RESTful Notifications 플랫폼으로도 Pocket Alert에 보낼 수 있어요:

notify:
  - name: pocketalert
    platform: rest
    resource: https://api.pocketalert.app/v1/messages
    method: POST_JSON
    title_param_name: title
    headers:
      Token: !secret pocketalert_token
    data:
      level: high

POST_JSON은 JSON 본문을 보내고, title_param_name은 알림 제목을 우리 title 필드에 매핑하며, data는 고정 필드를 추가해요. action: notify.pocketalert로 호출하면서 title과 message를 넘기세요. 수준은 알림기마다 고정되어 있으니, 여러 수준이 필요하면 수준별로 하나씩 만들거나, 버튼도 처리하는 rest_command를 그대로 쓰세요.

알림이 도착하지 않을 때

  • 로그를 확인하세요. 요청이 실패하면 rest_command가 상태 코드와 함께 경고를 남겨요. 401은 secrets.yaml의 키가 잘못됐다는 뜻이고, 400은 대개 페이로드가 올바른 JSON이 아니라는 뜻이에요.
  • 처음에는 재시작하세요. 처음 추가한 rest_command 블록은 Home Assistant를 재시작해야 액션이 나타나요. 이후 수정은 rest_command.reload 액션으로 반영돼요.
  • 개발자 도구에서 액션을 직접 실행하세요. 그게 잘 되면 문제는 자동화의 트리거나 조건에 있는 거예요. 추적 기록을 확인하세요.
  • 버튼이 동작하지 않을 때: 휴대폰 브라우저에서 웹훅 URL의 호스트를 열어 보세요. 휴대폰이 그 주소로 Home Assistant에 접속할 수 없다면 버튼도 동작하지 않아요.
  • 오늘의 한도를 확인하세요. 무료 플랜은 하루 50개 메시지에서 멈추는데, 수다스러운 센서라면 금방 다 쓸 수 있어요. 트리거에 for:를 넣으면 도움이 돼요.

FAQ

Home Assistant Companion 앱이 꼭 필요한가요?

아니요. 푸시는 Pocket Alert에서 오니까 휴대폰에는 Pocket Alert 앱만 있으면 돼요. 센서나 위치 추적을 위해 Companion 앱을 계속 써도 괜찮아요.

Home Assistant Cloud에서도 되나요?

네. rest_command는 Home Assistant에서 Pocket Alert API를 직접 호출하므로 Nabu Casa에 의존하지 않아요. Home Assistant Cloud는 외출 중에 밸브 버튼을 쓸 때만 도움이 돼요.

누수 알림으로 밤에 깰 수 있나요?

critical이라면 가능해요. iPhone에서는 무음 스위치를, Android에서는 방해 금지 모드를 무시하고 울려요. 이 수준은 유료 플랜이 필요해요. 무료 플랜에서는 high로 도착해요.

API 키가 노출되나요?

키는 secrets.yaml에 있고, HTTPS를 통해 Token 헤더로 전송돼요. Home Assistant 전용 키를 따로 만들어 두면, 다른 스크립트에 영향을 주지 않고 이 키만 폐기할 수 있어요.

무료 계정을 만들고, rest_command 하나만 추가해 보세요. 집이 필요할 때 알려 줄 거예요.

이 글 공유하기