블로그로 돌아가기

Uptime Kuma 푸시 알림을 휴대폰으로: 장애는 크게, 복구는 조용하게

Uptime Kuma 푸시 알림을 휴대폰으로: 장애는 크게, 복구는 조용하게

Uptime Kuma는 무언가 다운되었다는 사실을 잘 알아챕니다. 다만 그 알림이 어디로 가는지는 별개의 문제예요. 대부분은 하루 종일 휴대폰을 울리는 다른 알림들과 함께 텔레그램 그룹, 디스코드 채널, 이메일 폴더로 보냅니다. 그리고 "복구됨" 메시지는 "다운됨" 메시지와 똑같은 소리를 내기 때문에, 밤마다 상태가 오락가락하면 사람들은 결국 채널을 음소거하고 더는 읽지 않게 돼요.

이 가이드에서는 Uptime Kuma의 알림을 우선순위를 나눈 푸시 알림으로 Pocket Alert에 보내는 방법을 설명합니다. 모니터가 다운되면 high로 도착해서 iPhone의 집중 모드도 통과합니다. 복구는 low로 도착해요. 확인하면 피드에 남아 있지만 누구도 깨우지 않습니다. 모든 설정은 Uptime Kuma에 기본으로 들어 있는 Webhook 알림 유형을 사용하므로 따로 설치할 것이 없습니다.

아래 내용은 모두 Docker에서 실행한 Uptime Kuma 2.5.8로 테스트했습니다.

준비물

  • Uptime Kuma 2.x. 대부분은 1.23.x에서도 동작하며, 차이점은 맨 끝에 정리해 두었습니다.
  • 휴대폰에 설치한 Pocket Alert 앱과 계정. 계정이 없다면 회원가입을 해 주세요. 시작하는 데는 무료 플랜으로 충분합니다.
  • API Keys에서 발급한 API 키(방법 1) 또는 Webhooks에서 만든 웹훅(방법 2).

연결하는 두 가지 방법

Uptime Kuma의 Webhook 알림은 자체 JSON이나 직접 작성한 본문으로 어떤 URL에든 요청을 보낼 수 있습니다. 그래서 연결 방법이 두 가지예요.

방법 1: Pocket Alert API방법 2: Pocket Alert 웹훅 URL
전송 URLhttps://api.pocketalert.app/v1/messageshttps://p4a.me/wh/<slug>
푸시 제목직접 지정, 예: Down: Website항상 Webhook <name>
다운은 크게, 업은 조용하게예예, 사용자 지정 본문을 쓸 때. 그렇지 않으면 모든 알림이 같은 수준
Uptime Kuma에 저장되는 비밀 값계정 전체에 접근할 수 있는 API 키이 웹훅으로만 푸시를 만들 수 있는 URL
Pocket Alert의 요청 기록없음있음, 웹훅 기록에서 확인

제목을 읽기 쉽게 만들고 움직이는 부분을 최소화하고 싶다면 방법 1을 고르세요. 전체 API 키를 Uptime Kuma에 저장하고 싶지 않거나(Uptime Kuma는 헤더를 포함한 알림 설정을 일반 JSON으로 자기 데이터베이스에 보관합니다), 디버깅을 위해 보낸 모든 요청을 Pocket Alert 쪽에서 기록해 두고 싶다면 방법 2를 고르세요.

방법 1: Pocket Alert API로 바로 전송

Uptime Kuma에서 Settings → Notifications를 열고 Set Up Notification을 클릭하세요. 다음과 같이 입력합니다.

  • Notification Type: Webhook
  • Friendly Name: Pocket Alert
  • Post URL: https://api.pocketalert.app/v1/messages
  • HTTP Method: POST
  • Request Body: Custom Body

아래 내용을 본문 입력란에 붙여 넣고, kuma.example.com을 여러분의 Uptime Kuma 주소로 바꾸세요.

{%- assign level = "default" -%}
{%- assign title = "Uptime Kuma" -%}
{%- assign text = msg -%}
{%- if heartbeatJSON -%}
  {%- assign text = heartbeatJSON.msg | default: msg -%}
  {%- if heartbeatJSON.status == 0 -%}
    {%- assign title = "Down: " | append: monitorJSON.name -%}
    {%- assign level = "high" -%}
    {%- for tag in monitorJSON.tags -%}
      {%- if tag.name == "critical" -%}{%- assign level = "critical" -%}{%- endif -%}
    {%- endfor -%}
  {%- else -%}
    {%- assign title = "Up: " | append: monitorJSON.name -%}
    {%- assign level = "low" -%}
  {%- endif -%}
{%- elsif msg contains "will expire" -%}
  {%- assign title = "Expiring soon" -%}
{%- endif -%}
{
  "title": {{ title | json }},
  "message": {{ text | json }},
  "level": "{{ level }}",
  "actions": [
    {
      "type": "view",
      "label": "Open in Uptime Kuma",
      "value": "https://kuma.example.com/dashboard/{{ monitorJSON.id }}"
    }
  ]
}

그다음 Additional Headers를 켜고 아래 내용을 붙여 넣으세요.

{
  "Token": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

본문이 하는 일은 다음과 같습니다.

  • 본문은 Liquid 템플릿입니다. Uptime Kuma는 msg(미리 만들어진 텍스트), monitorJSON(모니터), heartbeatJSON(상태가 바뀐 점검)을 넘겨줍니다. heartbeatJSON.status는 다운일 때 0, 업일 때 1입니다.
  • | json은 따옴표를 포함한 완전한 JSON 문자열을 만듭니다. 오류 메시지나 모니터 이름에는 따옴표와 역슬래시가 들어갈 수 있는데, 이 필터를 쓰면 요청이 깨지지 않아요. Bob's "main" site라는 이름의 모니터도 올바른 JSON을 만듭니다.
  • 다운은 high, 업은 low입니다. high는 iPhone에서 시간에 민감한 알림으로 처리되어 집중 모드와 예약 요약도 통과합니다. low는 방해하지 않고 전달됩니다.
  • 모니터에 critical 태그를 붙이면 더 크게 울립니다. Uptime Kuma에서 가장 중요한 모니터에 critical이라는 이름의 태그를 추가하면, 그 모니터의 장애는 critical로 보내져 무음 스위치와 방해 금지 모드에서도 소리가 납니다. 중요 알림은 유료 기능이며, 무료 플랜에서는 high로 전달됩니다.
  • 인증서 알림과 테스트 메시지에는 점검 정보가 없습니다. 이런 경우 푸시는 Uptime Kuma가 만든 텍스트를 메시지로 사용합니다. 핑 모니터가 다시 올라올 때처럼 점검 메시지가 비어 있을 때도 같은 텍스트를 대신 씁니다. API는 메시지가 비어 있는 푸시를 거부하기 때문입니다.
  • 버튼은 모니터를 엽니다. /dashboard/<id>는 Uptime Kuma에서 해당 모니터의 페이지입니다. 인증서 경고에는 모니터 ID가 없으므로 버튼은 대시보드를 엽니다. 액션 버튼은 유료 기능이며, 무료 플랜에서는 API가 버튼을 빼고 푸시를 전달합니다. 액션 버튼으로 할 수 있는 다른 기능은 액션 버튼을 참고하세요.

Content-Type 헤더를 빼먹지 마세요. Uptime Kuma는 사용자 지정 본문을 보낼 때 따로 지정하지 않으면 application/x-www-form-urlencoded로 표시합니다. 제 테스트에서도 그렇게 전송되었어요. Pocket Alert API는 JSON이나 multipart만 받으며, 이런 요청에는 400으로 응답합니다.

Test를 클릭하세요. "Uptime Kuma" 제목에 "Pocket Alert Testing" 텍스트가 담긴 푸시가 몇 초 안에 도착해야 합니다. 그다음 저장하세요.

다음은 Uptime Kuma 2.5.8에서 실제 장애와 복구가 발생했을 때 보낸 내용입니다.

{
  "title": "Down: Website",
  "message": "timeout of 4000ms exceeded",
  "level": "high",
  "actions": [
    { "type": "view", "label": "Open in Uptime Kuma", "value": "https://kuma.example.com/dashboard/1" }
  ]
}
{
  "title": "Up: Website",
  "message": "200 - OK",
  "level": "low",
  "actions": [
    { "type": "view", "label": "Open in Uptime Kuma", "value": "https://kuma.example.com/dashboard/1" }
  ]
}

Uptime Kuma 이름을 붙인 별도의 API 키를 사용하세요. 그래야 서버가 노출되었을 때 이 키만 단독으로 폐기할 수 있습니다.

방법 2: Pocket Alert 웹훅 URL

이 방법에서는 Uptime Kuma가 자체 JSON을 Pocket Alert 웹훅으로 보내고, Pocket Alert 쪽의 템플릿이 이를 푸시로 바꿔 줍니다.

웹훅 만들기

버튼 템플릿은 API로만 설정할 수 있으므로, 가장 빠른 방법은 호출 한 번입니다. 이 호출은 메시지 템플릿, 기본 수준 high(1), "Open in Uptime Kuma" 버튼이 있는 "Uptime Kuma" 이름의 웹훅을 만들고, 수신 URL을 출력합니다.

PA_KEY='your-api-key'
KUMA_URL='https://kuma.example.com'

jq -n --arg kuma "$KUMA_URL" '{
  name: "Uptime Kuma",
  message: "%msg%",
  default_level: 1,
  actions: ([{type: "view", label: "Open in Uptime Kuma", value: ($kuma + "/dashboard/%monitor.id%")}] | tojson)
}' |
curl -sS https://api.pocketalert.app/v1/webhooks \
  -H "Token: $PA_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- |
jq -r '"Receive URL: https://p4a.me/wh/" + .url'

명령어보다 클릭이 편하다면 Webhooks의 콘솔에서 만드세요. 이름은 Uptime Kuma, Default priority는 High, 메시지는 %msg%로 설정합니다. 버튼만 없을 뿐 같은 푸시를 받을 수 있습니다.

Uptime Kuma에서 웹훅 지정하기

새 알림을 Webhook 유형으로 설정하고, 수신 URL을 Post URL에 붙여 넣은 다음, Request Body를 Preset - application/json으로 지정하세요. 헤더는 필요하지 않습니다. URL 자체가 비밀 값이므로 비밀번호처럼 다루세요. multipart 프리셋은 고르지 마세요. Pocket Alert 웹훅은 JSON만 읽습니다.

제 테스트 환경에서 모니터가 다운되었을 때 Uptime Kuma가 보낸 내용입니다(줄여서 옮겼습니다. monitor 객체에는 약 100개의 필드가 있어요).

{
  "heartbeat": {
    "monitorID": 1,
    "status": 0,
    "time": "2026-10-31 16:09:56.331",
    "msg": "timeout of 4000ms exceeded",
    "important": true,
    "localDateTime": "2026-10-31 16:09:56"
  },
  "monitor": {
    "id": 1,
    "name": "Website",
    "url": "http://tls-target/",
    "type": "http",
    "tags": []
  },
  "msg": "[Website] [🔴 Down] timeout of 4000ms exceeded"
}

%msg% 템플릿은 최상위 msg를 사용합니다. 모든 요청에 항상 들어 있는 필드이기 때문이에요. 인증서 경고와 테스트 메시지에서는 heartbeat와 monitor가 null이고 msg만 채워집니다. 푸시는 "Webhook Uptime Kuma" 제목에 "[Website] [🔴 Down] timeout of 4000ms exceeded" 텍스트로 도착합니다. 경로가 없는 플레이스홀더는 빈 문자열로 바뀌므로, 인증서 경고에서도 버튼은 /dashboard/를 가리키고 정상적으로 동작합니다.

이 방법에서 다운은 크게, 업은 조용하게

JSON 프리셋을 쓰면 모든 요청에 웹훅의 기본 수준이 적용되므로 복구도 장애만큼 크게 울립니다. 이를 고치려면 Request Body를 Custom Body로 바꾸고 level 필드를 직접 보내세요. Pocket Alert 웹훅은 페이로드의 최상위 level을 먼저 읽고, 없을 때만 기본값을 씁니다.

{
  "level": "{% if heartbeatJSON %}{% if heartbeatJSON.status == 0 %}high{% else %}low{% endif %}{% else %}default{% endif %}",
  "msg": {{ msg | json }},
  "monitor": { "id": "{{ monitorJSON.id }}" }
}

본문은 msg와 monitor.id 필드 이름을 그대로 유지하므로, 웹훅의 메시지 템플릿과 버튼 템플릿은 수정 없이 동작합니다. Pocket Alert 웹훅은 Content-Type과 상관없이 본문을 JSON으로 읽으므로, 이 방법에는 추가 헤더가 필요하지 않습니다.

모든 모니터에 적용하기

모니터가 알림을 사용하기 전까지 알림은 아무 일도 하지 않습니다. 알림 양식 아래쪽에 스위치가 두 개 있어요.

  • Default enabled를 켜면 앞으로 만드는 모든 모니터에 이 알림이 자동으로 켜집니다.
  • Apply on all existing monitors를 켜면 이미 있는 모든 모니터에 알림이 추가됩니다. 저장할 때 한 번만 실행되며, 이 설정은 기억되지 않습니다.

처음 저장할 때 두 스위치를 모두 켜세요. 특정 모니터에서 알림을 빼고 싶다면 해당 모니터의 편집 양식을 열고 알림 체크를 해제하세요.

인증서 만료 경고

Uptime Kuma는 TLS 인증서가 만료되기 전에 미리 경고할 수 있습니다. HTTP(s) 모니터(Keyword 및 JSON Query 모니터에도 있음)를 열고 Advanced에서 Certificate Expiry Notification을 체크하세요. Ignore TLS/SSL errors for HTTPS websites가 켜져 있으면 이 항목은 회색으로 비활성화됩니다.

기준 일수는 전역 설정으로, Settings → Notifications → TLS Certificate Expiry에서 바꿀 수 있으며 기본값은 7일, 14일, 21일입니다. 경고는 모니터의 장애 알림과 같은 알림 채널로 가며, 다음과 같은 텍스트가 담깁니다.

[TLS site][https://tls-target/] server certificate tls-target will expire in 4 days

방법 1의 본문은 msg contains "will expire" 조건으로 이 경고를 잡아서, default 수준의 "Expiring soon" 제목으로 보냅니다. Uptime Kuma는 점검할 때마다 보내지 않고 기준 일수마다 한 번만 보냅니다. 제 테스트에서는 만료 4일 전인 인증서를 대상으로 모니터가 119번 점검되었지만, 경고는 정확히 한 번만 발송되었습니다.

불안정한 모니터가 휴대폰을 가득 채우지 않게 하기

모니터 설정 세 가지가 불안정한 서비스가 얼마나 시끄러울지를 결정합니다.

설정역할권장 값
Retries모니터가 다운으로 판단하기 전에 Pending으로 표시되는 실패 점검 횟수. Pending 상태의 점검은 알림을 보내지 않습니다.2 또는 3
Heartbeat Retry IntervalPending 상태일 때 점검 사이의 간격(초).20~60
Resend Notification if Down X times consecutively이 횟수만큼 추가로 점검이 실패하면 다운 알림을 다시 보냅니다. 0이면 한 번만 보냅니다.0, 또는 30~60분이 되는 값

제 테스트에서 Retries를 2로 설정하자, 처음 실패한 두 점검은 pending으로 표시되었고 세 번째 점검에서만 "Down" 알림이 갔습니다. Resend를 3으로 설정하자, 서비스가 복구될 때까지 실패 점검이 세 번 더 발생할 때마다 다운 알림이 반복되었습니다. 재전송 횟수는 분이 아니라 점검 횟수로 셉니다. 점검 간격이 60초라면 30은 30분마다 한 번씩 알린다는 뜻입니다.

다운, 업, 재전송은 모두 메시지 하나로 계산됩니다. 무료 플랜은 하루 50개까지 허용하므로, 재시도 없이 상태가 오락가락하는 모니터 하나만 있어도 오후 한나절이면 한도를 다 쓸 수 있습니다. 재시도 설정이 가장 간단하고 효과적인 해결책입니다.

아무것도 도착하지 않을 때

  • 테스트가 HTTP 400으로 실패합니다. 방법 1에서는 Additional Headers에 "Content-Type": "application/json"이 있는지 확인하세요. 없으면 요청이 폼 데이터로 전송됩니다.
  • HTTP 401이 나옵니다. Token 헤더가 없거나 키가 폐기된 것입니다. API Keys에서 새 키를 만드세요.
  • 테스트 알림은 도착하는데 장애 알림이 오지 않습니다. 모니터를 열고 알림이 체크되어 있는지 확인하세요. 또한 Uptime Kuma는 모니터가 처음 점검에서 정상이면 알림을 보내지 않으므로, 새 모니터는 무언가 바뀌기 전까지 조용합니다.
  • 방법 2에서 아무것도 보이지 않습니다. 콘솔에서 웹훅 기록을 확인하세요. 요청이 기록되어 있고 오류가 있다면 이유가 함께 표시됩니다. 잘못된 JSON이거나 빈 메시지를 만든 템플릿일 수 있습니다. 기록이 아예 없다면 Uptime Kuma가 p4a.me에 도달하지 못한 것입니다. 웹훅 테스터로 요청을 보내 보면 Uptime Kuma가 정확히 무엇을 보내는지 확인할 수 있습니다.
  • 복구 알림이 없는 것 같습니다. low 푸시는 소리가 나지 않습니다. 앱의 피드를 확인해 보세요.

FAQ

이 방법에는 어떤 Uptime Kuma 버전이 필요한가요?

2.5.8에서 테스트했으며, 작성 시점의 최신 릴리스입니다. 1.23.x에도 사용자 지정 본문과 추가 헤더가 있는 Webhook 유형이 있으며, 템플릿에서 같은 msg, monitorJSON, heartbeatJSON 변수를 쓸 수 있습니다. 방법 1의 본문을 1.23.16에 포함된 템플릿 엔진으로 렌더링해 보았더니 같은 JSON이 나왔지만, 전체 종단 간 테스트는 2.5.8에서만 진행했습니다.

Uptime Kuma를 실행하는 서버가 다운되면 어떻게 되나요?

그러면 아무 알림도 가지 않습니다. Uptime Kuma는 자기 자신의 장애를 보고할 수 없으므로, 다른 기기에서 실행하는 점검이나 호스팅형 모니터처럼 외부에서 상태를 확인하는 것을 따로 두세요. 업타임 모니터링 페이지에 Pocket Alert 웹훅과 함께 쓸 수 있는 호스팅형 모니터 목록이 있습니다.

모니터마다 다른 휴대폰으로 보낼 수 있나요?

유료 플랜에서는 가능합니다. 그룹마다 알림을 하나씩 만들고, 본문(방법 1)에서 서로 다른 device_id를 지정하거나, 각자 기기를 지정한 다른 웹훅(방법 2)을 쓰세요. 그리고 각 모니터에서 알맞은 알림을 체크하면 됩니다. 무료 플랜은 기기 하나와 웹훅 하나만 허용하므로, 알림을 보낼 휴대폰도 하나뿐입니다.

핑, 포트, DNS 모니터에도 되나요?

네. 본문은 모니터의 이름과 ID, 그리고 점검의 상태와 메시지만 사용하는데, 모든 모니터 유형에 이 정보가 있습니다. 핑을 포함한 일부 유형은 점검이 성공하면 메시지를 비워 두는데, 이때는 본문이 Uptime Kuma의 기본 텍스트로 대신합니다. 버튼은 점검 대상 주소가 아니라 Uptime Kuma에 있는 모니터 페이지로 연결되므로, 주소가 URL이 아니어도 동작합니다.

이미 Proxmox에서 이 방식을 쓰고 있습니다. API 키를 공유해도 되나요?

공유할 수는 있지만, 한쪽을 폐기해도 다른 쪽이 깨지지 않도록 Uptime Kuma에는 별도의 키를 주세요. 같은 홈랩의 백업 및 디스크 알림은 Proxmox 가이드에서 다룹니다.

무료 계정을 만들고, 본문을 Webhook 알림에 붙여 넣어 보세요. 다음 장애는 바로 휴대폰에 도착하고, 복구 알림은 피드에서 조용히 기다리게 됩니다.

이 글 공유하기