# 자체 호스팅 스택에서 아이폰 푸시 알림을 안정적으로 받기

> 홈랩에서 아이폰 푸시 알림이 어려운 이유, 안정적인 경로의 모습, 그리고 Grafana, Uptime Kuma, n8n, 크론 작업, 셸 스크립트를 시간에 민감한 알림과 중요 알림에 연결하는 방법을 알려드려요.

*04.11.2026*

<!-- source: https://pocketalert.app/ko/blog/self-hosted-iphone-push-notifications -->

Grafana 알림이 새벽 3시에 울렸어요. 서버 로그에는 웹훅 호출이 성공했다고 남아 있어요. 그런데 아이폰은 조용하기만 해요. 자체 호스팅 모니터링은 장애를 감지하는 데 뛰어나요. 하지만 메시지를 휴대폰까지 전달하는 단계에서 대부분의 홈랩 구성이 무너져요.

이 가이드에서는 자체 호스팅 스택에서 아이폰 푸시 알림이 왜 어려운지, 안정적인 경로가 어떤 모습인지, 그리고 Grafana, Uptime Kuma, n8n, 크론 작업, 셸 스크립트를 어떻게 연결하는지 설명해요. 첫 알림이 작동하기까지 5분 정도 걸려요.

## iOS 푸시 알림이 자체 호스팅 환경에서 깨지는 이유

### 아이폰에 도달할 수 있는 것은 APNs뿐이에요

아이폰으로 가는 모든 푸시는 Apple Push Notification service(APNs)를 거쳐요. 서버가 휴대폰과 직접 연결을 열고 데이터를 보낼 수는 없어요. 휴대폰은 Apple과 하나의 장기 연결을 유지해요. 서버는 Apple 개발자 계정의 키로 인증해서 HTTP/2로 APNs에 각 메시지를 보내요. 그러면 APNs가 휴대폰과 이미 맺어진 연결을 통해 메시지를 전달해요.

따라서 스택 중간에 APNs를 호출할 수 있는 발신자가 필요해요. 휴대폰은 서버를 폴링하지 않으므로, 내부 네트워크에 있는 일반 웹훅 엔드포인트는 전달할 대상이 없어요. 전달 경로를 더 자세히 알고 싶다면 [푸시 알림이 아이폰에 도달하는 방식](/blog/how-push-notifications-work-apns-fcm)을 참고하세요.

### 직접 발신자를 운영하는 일은 생각보다 많아요

APNs와 직접 통신할 수는 있어요. 서명 키(토큰 인증에 쓰는 `.p8` 파일은 매년 만료되지 않고, 앱마다 쓰는 TLS 클라이언트 인증서는 만료돼요), 등록된 앱, 기기 토큰을 저장하는 방법, APNs 오류와 재시도를 처리하는 코드가 필요해요. 기기를 등록하고 알림을 표시하는 iOS 앱도 있어야 해요. 각 부분은 혼자서는 감당할 만해요. 진짜 비용은 키 교체와 Apple 정책 변경을 거치면서도 이 모든 것이 계속 작동하게 유지하는 일이에요.

대부분의 셀프 호스팅 사용자가 원하는 것은 배관 작업이 아니라 결과예요. APNs 쪽을 이미 운영하는 호스팅 서비스를 쓰면 스택을 단순하게 유지할 수 있어요. 알림 하나당 HTTP 요청 한 번이면 돼요.

### 집중 모드, 음소거, 중요도 수준

iOS는 각 알림의 중요도 수준, 사용 중인 집중 모드, 앱 설정에 따라 알림을 얼마나 크게 보여 줄지 결정해요. 알림에서 중요한 것은 세 가지예요.

1. **앱에 알림이 허용되어 있어야 해요.** iOS 설정에서 가장 먼저 확인하세요. 서버가 아무리 잘 동작해도 알림이 꺼진 앱은 알림을 표시하지 않아요.
2. **시간에 민감한 알림은 집중 모드를 뚫고 와요.** Pocket Alert에서 `high` 메시지는 시간에 민감한 알림으로 도착해요. 더 낮은 수준은 집중 모드가 끝날 때까지 기다려요.
3. **중요 알림은 무음 스위치와 방해 금지 모드를 무시해요.** 이 알림에는 Apple이 심사 후 허용하는 특별한 권한이 필요해요. Pocket Alert는 이 권한을 갖추고 있어요. 유료 플랜의 `critical` 메시지는 앱에 중요 알림을 허용해 두었다면 휴대폰이 음소거 상태여도 소리를 재생해요. 이 권한을 껐다면 시간에 민감한 알림으로 도착해요.

중요도 설정 방법은 아래 우선순위 섹션에서 다뤄요.

## 안정적인 설정의 모습

스택이 문제를 감지하고 HTTP 요청을 한 번 보내요. 그 다음은 호스팅 서비스가 처리해요.

```
Grafana / Uptime Kuma / n8n / cron + CLI
        │  HTTPS (API call or webhook)
        ▼
Pocket Alert  ──►  APNs  ──►  iPhone (Pocket Alert app)
```

작업은 다음과 같이 나뉘어요.

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>스택이 하는 일</th><th>Pocket Alert가 하는 일</th></tr></thead>
<tbody>
<tr><td>장애를 감지하고 무엇이 중요한지 판단해요</td><td>요청을 받고 API 키 또는 웹훅 URL을 확인해요</td></tr>
<tr><td>텍스트를 구성하거나 자체 JSON을 보내요</td><td>필드를 매핑하고, 중요도 수준을 설정하고, APNs로 전달해요</td></tr>
<tr><td>이벤트가 발생할 때 한 번만 보내요</td><td>계정의 모든 기기 또는 지정한 기기로 푸시를 보내요</td></tr>
<tr><td>자체 로그를 보관해요</td><td>메시지 기록과 웹훅별 요청 로그를 보관해서, 무엇이 도착했고 무엇이 실패했는지 확인할 수 있어요</td></tr>
</tbody>
</table>
</div>

## curl로 첫 알림 보내기

[pocketalert.app/signup](/signup)에서 회원가입하고 [API 키](/account/apikeys) 페이지를 열어 **Create New Key**를 클릭하세요. 키는 한 번만 표시되니 안전한 곳에 복사해 두세요.

환경 변수에 저장하고 메시지를 보내세요.

```bash
export PA_KEY="YOUR_API_KEY"

curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: $PA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Backup finished",
    "message": "nightly-backup on nas01 completed in 14m",
    "level": "high"
  }'
```

호출이 성공하면 `tid`, `title`, `message`, `application`, `device`, `created_at`이 담긴 JSON이 반환돼요. 나중에 푸시를 로그 줄과 대조하고 싶다면 `tid`를 보관해 두세요.

자주 실수하는 부분이 세 가지 있어요.

- **Content-Type을 설정하세요.** API는 JSON이나 `multipart/form-data`를 받아요. 헤더를 빼고 `application/x-www-form-urlencoded`로 보내면 전송되는 `curl -d`는 거부돼요. JSON 본문이라면 `-H "Content-Type: application/json"`을 쓰고, 폼 필드라면 `-F`를 쓰세요.
- **`title`과 `message`는 필수예요.** 그 밖의 값은 모두 선택이에요.
- **계정의 모든 기기에 보내려면 `device_id`를 생략하세요.** 휴대폰이 여러 대이고 특정 기기에만 보내려면 추가하세요.

## 명령줄에서 알림 보내기

[Pocket Alert CLI](/tools/cli)는 기존 스크립트에 알림을 연결하는 가장 빠른 방법이에요. 셸 스크립트, Homebrew, Go 중 하나로 설치하세요.

```bash
curl -fsSL https://raw.githubusercontent.com/PocketAlert/cli/main/install.sh | sh
# or
brew install pocketalert/tap/pocketalert
# or
go install github.com/PocketAlert/cli/cmd/pocketalert@latest
```

`pocketalert auth`를 한 번 실행하고 키를 붙여 넣으세요. 키는 본인만 읽을 수 있도록 `~/.pocketalert/config.json`에 저장돼요. 서버, 컨테이너, CI에서는 대신 `POCKETALERT_API_KEY`를 설정하세요.

메시지를 보내려면 이렇게 하세요.

```bash
pocketalert send "Deploy finished" "v2.4.0 is live" --level high
```

명령 출력을 바로 알림으로 보낼 수도 있어요.

```bash
df -h | pocketalert send "Disk report" --level default
```

또는 `exec`로 명령을 감싸세요. 명령은 평소처럼 실행되고, 종료 상태, 실행 시간, 마지막 출력 줄을 담은 푸시가 한 번 전송된 뒤 종료 코드가 그대로 전달돼요.

```bash
pocketalert exec -t "Database dump" -- ./dump.sh
```

`-q`를 쓰면 메시지 ID만 출력되어 스크립트 작성에 편리해요. 어떤 명령에든 `--json`을 붙이면 기계가 읽을 수 있는 출력을 받을 수 있어요.

## 필드 매핑이 있는 웹훅

이미 JSON을 보내는 소스(Grafana, Uptime Kuma, 또는 직접 만든 서비스)를 쓴다면 발신자를 따로 만들 필요가 없어요. [웹훅](/webhooks)에서 콘솔을 통해 웹훅을 만들면 `https://p4a.me/wh/1234abcd` 같은 수신 URL이 생겨요. 슬러그는 추측할 수 없고, 각 URL은 웹훅 하나와 애플리케이션 하나에 연결돼요. 소스를 이 URL로 `POST` 요청을 보내도록 설정하세요.

푸시 제목은 "Webhook"과 웹훅 이름을 합친 형태로 표시돼요. 그러니 **Grafana**처럼 소스 이름으로 짓는 것이 좋아요. 메시지 템플릿은 GJSON 경로를 사용해 들어오는 JSON에서 값을 가져와요.

- 중첩된 필드는 `%object.field%`
- 배열 항목은 `%items.0.name%`
- 개수는 `%users.#%`
- 템플릿 전체를 `*`로 두면 본문 전체를 보내요

예를 들어 다음과 같은 들어오는 페이로드가 있다면,

```json
{
  "service": "api-gateway",
  "check": "tls-expiry",
  "state": "warning",
  "detail": "certificate expires in 6 days"
}
```

템플릿은 이렇게 쓸 수 있어요.

```
[%state%] %service%: %check%
%detail%
```

경로가 없는 자리표시자는 빈 문자열로 렌더링되므로, 오타는 오류가 아니라 텍스트의 빈 공간으로 나타나요.

템플릿을 작성하기 전에 실제 페이로드를 확인하세요. [웹훅 테스터](/tools/webhook)를 열고 테스트 URL을 복사한 다음, 소스가 그 URL로 보내도록 설정하세요. 테스터는 메서드, 헤더, 본문을 보여 주므로, 소스가 실제로 보내는 값에 맞춰 경로를 작성할 수 있어요. 운영 환경의 비밀 값은 공개 테스트 URL로 보내지 마세요. URL을 아는 누구나 그곳에 도착한 내용을 읽을 수 있어요.

중요도는 두 가지 방식으로 설정할 수 있어요. 웹훅에 기본 수준을 설정하거나, 페이로드 최상위에 `level` 필드를 넣으면 기본값보다 우선해요. 유효한 값은 `silent`, `low`, `default`, `high`, `critical`이나 `-2`에서 `2` 사이의 숫자예요. 잘못된 `level`은 무시되고 웹훅의 기본값이 적용돼요.

## 연동

### Grafana 알림

콘솔에서 다음 메시지 템플릿을 사용해 **Grafana**라는 이름의 웹훅을 만드세요.

```
[%status%] %commonLabels.alertname% (%commonLabels.severity%)
%alerts.0.annotations.summary%
```

수신 URL을 복사하세요. Grafana에서 **Alerting → Contact points → Add contact point**로 이동해 **Webhook** 연동을 선택하고 다음과 같이 설정하세요.

```
Integration: Webhook
URL:         https://p4a.me/wh/1234abcd
Method:      POST
```

일치하는 알림이 이 연락 지점으로 라우팅되도록 알림 정책에 연락 지점을 연결한 다음, 연락 지점의 **Test** 버튼을 누르세요. `HighCPU` 레이블이 있는 `severity="critical"`라는 알림이 발생하면 `[firing] HighCPU (critical)`로 표시돼요. 알림이 해제되면 같은 푸시가 대괄호 안에 `resolved`를 담아 도착해요.

참고할 점이 세 가지 있어요. 규칙에서 `severity` 레이블을 설정하지 않으면 해당 부분은 비어 있어요. 템플릿은 그룹의 첫 번째 알림(`alerts.0`)만 읽으므로, 한 알림에 여러 경고가 묶여 있으면 첫 번째 요약만 보여요. 그리고 각 규칙의 대기 기간(예: 5분)은 값이 계속 바뀌는 지표 때문에 휴대폰이 1분마다 울리는 일을 막는 가장 간단한 방법이에요. 더 많은 필드는 [Grafana 가이드](/blog/how-to-integrate-grafana-into-pocketalert)에서 확인할 수 있어요.

### Uptime Kuma

Uptime Kuma는 상태가 바뀔 때마다 웹훅을 보내요. 유형이 **Webhook**인 알림을 추가하고, **Post URL**을 수신 URL로 설정한 뒤 요청 본문은 JSON 프리셋으로 두세요.

Pocket Alert에서는 템플릿으로 `%msg%`를 사용하세요. `msg`는 인증서 경고와 테스트 메시지를 포함해 Uptime Kuma가 보내는 모든 요청에 있는 유일한 필드예요. 이미 "[Website] [🔴 Down] timeout of 4000ms exceeded"처럼 읽히는 문장이에요. 웹훅의 기본 수준은 `high`로 설정하세요.

프리셋 본문을 쓰면 Uptime Kuma가 스스로 `level` 필드를 추가하지 않으므로, 복구 알림도 장애 알림만큼 크게 도착해요. 장애에는 `high`, 복구에는 `low`를 보내는 사용자 정의 본문은 [Uptime Kuma 가이드](/blog/uptime-kuma-notifications)에서 보여 드려요.

### n8n

n8n 워크플로에서 문제를 감지하는 단계 뒤에 **HTTP Request** 노드를 추가하세요.

- **Method:** `POST`
- **URL:** `https://api.pocketalert.app/v1/messages`
- **Authentication:** Generic Credential Type, 그다음 Header Auth. 이름은 `Token`, 값은 API 키.
- **Send Body:** 켜기, **Body Content Type**은 JSON, **Specify Body**는 Using JSON, 그리고 객체 전체를 만드는 표현식을 입력하세요.

```
{{ JSON.stringify({
  title: 'Disk almost full on ' + $json.host,
  message: $json.detail,
  level: 'high'
}) }}
```

`JSON.stringify`는 값 안의 따옴표와 줄바꿈을 이스케이프해요. JSON 문자열 안에 그냥 `"{{ $json.detail }}"`를 쓰면 이렇게 처리되지 않아요. 모든 워크플로의 실패를 잡으려면 **Error Trigger**로 시작하는 오류 워크플로를 설정하세요. 실패한 워크플로의 이름은 `$json.workflow.name`에, 오류 내용은 `$json.execution.error.message`에 있어요. 바로 가져와 쓸 수 있는 워크플로는 [n8n 가이드](/blog/n8n-push-notifications)에 있어요.

## 예약 및 반복 점검

크론 작업은 조용히 실패하는데, 그럴 때 알림을 놓치면 가장 곤란해요. 알림을 작업 자체에 넣으세요.

```bash
POCKETALERT_API_KEY=YOUR_API_KEY
PATH=/usr/local/bin:/usr/bin:/bin
0 3 * * * pocketalert exec -t "Nightly backup" -- /opt/scripts/backup.sh
```

크론은 셸 프로필을 불러오지 않으므로, 맨 위의 두 줄이 작업에 키와 CLI가 포함된 `PATH`를 제공해요. 성공한 실행은 기본 수준으로 "✓ Nightly backup"이라고 도착해요. 실패한 실행은 `high` 수준으로 "✗ Nightly backup (exit 1)"이라고 도착하고, 메시지에는 출력의 마지막 줄이 담겨요. 실패 알림만 받고 싶다면 `--on failure`를 추가하세요.

`exec`는 작업이 실패했을 때를 알려 주지만, 아예 실행되지 않았을 때는 알려 주지 않아요. 이때는 [크론 작업 모니터링 가이드](/blog/cron-job-monitoring-healthchecks)에 나온 것처럼 데드맨 스위치와 함께 쓰세요.

일정이 맞는지 확신이 없다면 무료 [크론 표현식 도구](/tools/cron)에 붙여 넣으세요. 각 필드를 쉬운 말로 풀어 주고 다음 실행 시각 목록을 보여 줘요. 다음 실행 시각은 브라우저의 시간대를 기준으로 하므로, 서버의 시간대와 다를 수 있어요.

## 중요도 수준과 중요 알림

조용한 수준부터 큰 수준까지 다섯 가지 수준을 쓸 수 있어요.

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>수준</th><th>값</th><th>아이폰에서</th><th>일반적인 용도</th></tr></thead>
<tbody>
<tr><th><code>silent</code></th><td>-2</td><td>소리 없이 알림 센터로 바로 전달</td><td>"Resolved" 이벤트, 나중에 읽을 수 있는 로그</td></tr>
<tr><th><code>low</code></th><td>-1</td><td>수동적으로 표시되며 화면을 켜지 않음</td><td>정보성 알림</td></tr>
<tr><th><code>default</code></th><td>0</td><td>소리가 나는 일반 알림</td><td>완료된 백업처럼 정기적인 결과</td></tr>
<tr><th><code>high</code></th><td>1</td><td>시간에 민감하며 집중 모드를 뚫고 옴</td><td>곧 확인이 필요한 경우</td></tr>
<tr><th><code>critical</code></th><td>2</td><td>중요 알림, 음소거 상태에서도 소리가 남</td><td>지금 바로 확인이 필요한 경우. 유료 플랜 전용</td></tr>
</tbody>
</table>
</div>

무료 플랜에서는 `critical` 메시지가 `high`로 전달돼요. 여전히 시간에 민감한 알림으로 즉시 도착하지만, 무음 스위치는 따라요.

발생한 알림과 그 해제에 대해 합리적인 매핑은 다음과 같아요.

- 발생: `high`, 또는 깨어날 가치가 있는 몇 가지에만 `critical`
- 해제: `silent`

웹훅의 기본 수준으로 설정하거나, 소스가 보낼 수 있다면 페이로드의 `level` 필드로 설정하세요.

## 체크리스트: 알림이 도착하는지 확인하기

1. iOS 설정에서 Pocket Alert 앱의 **알림 허용**을 켜세요. 시간에 민감한 알림과, 유료 플랜이라면 중요 알림도 함께 허용하세요.
2. **집중 모드를 켠 상태에서 테스트하세요.** 평소 쓰는 집중 모드를 켜고 위의 curl 명령으로 `high` 테스트를 보낸 뒤, 알림이 도착하는지 확인하세요. 도착하지 않으면 해당 집중 모드의 앱 알림 설정을 확인하세요.
3. **호출이 Pocket Alert에 도달했는지 확인하세요.** API 메시지는 앱과 웹 콘솔의 메시지 기록에 나타나요. 거부된 호출을 포함한 웹훅 호출은 해당 웹훅의 요청 로그에 나타나요. 호출이 기록되어 있다면 문제는 휴대폰에 있어요. 기록이 없다면 문제는 소스에 있어요.
4. **소스의 로그에서 나가는 요청을 확인하세요.** URL, 상태 코드, 응답 본문을 보세요.
5. **일일 한도를 살펴보세요.** 무료 플랜은 하루 50개의 알림을 허용해요. 값이 계속 바뀌는 점검 하나가 한 시간 만에 이 한도를 다 쓸 수 있으니, 규모를 키우기 전에 임계값과 대기 기간을 조정하세요. `pocketalert usage`로 오늘 남은 개수를 확인할 수 있어요.

그래도 알림이 도착하지 않는다면 다음 순서대로 확인하세요. 소스 로그, Pocket Alert 기록, 그다음 수준과 기기 설정이에요. 이 순서로 보면 실패한 단계를 빠르게 찾을 수 있어요.

## FAQ

**Apple 개발자 설정 없이도 아이폰에 푸시 알림을 보낼 수 있나요?**
네. APNs에 이미 연결된 호스팅 서비스가 Apple 쪽 작업을 처리해요. API 키를 담아 HTTP 요청을 보내면 서비스가 아이폰 앱으로 전달해요. 직접 발신자를 운영하려면 서명 키, 앱 등록, 자체 iOS 앱이 필요해요.

**자체 호스팅 알림이 늦게 오거나 아예 오지 않는 이유는 무엇인가요?**
보통 세 가지 중 하나예요. 앱에 알림이 허용되어 있지 않거나, 활성화된 집중 모드가 알림 수준을 막고 있거나, 요청이 서비스에 도달하지 못한 경우예요. 메시지 기록이나 웹훅 로그를 먼저 확인하면 어떤 경우인지 알 수 있어요.

**집중 모드가 켜져 있어도 알림이 도착하나요?**
알림이 허용되어 있다면 `high` 메시지는 시간에 민감한 알림으로 도착해서 집중 모드를 뚫을 수 있어요. 유료 플랜의 `critical` 메시지는 한 걸음 더 나아가 휴대폰이 음소거 상태여도 소리를 내요. 더 낮은 수준은 기다려요. 의존하기 전에 본인의 집중 모드 설정을 직접 테스트해 보세요.

**무료 플랜이 있나요?**
네. 무료 플랜에는 하루 50개의 알림, 기기 1대, 애플리케이션 1개, 웹훅 1개가 포함돼요. 무료 플랜에서는 중요 메시지가 높은 우선순위로 전달돼요.

## 다음 단계

약 5분이면 첫 아이폰 알림을 받을 수 있어요.

1. [회원가입](/signup)하고 아이폰에 앱을 설치하세요.
2. [API 키](/account/apikeys)에서 API 키를 만드세요.
3. 이 가이드의 curl 명령을 실행하세요.

이것이 작동하면 실제 소스 하나를 연결해 보세요. Grafana 연락 지점, Uptime Kuma 알림, 또는 크론 작업이 좋아요. 더 많은 홈랩 소스는 [홈랩 알림](/use-cases/homelab-alerts)과 [Proxmox 가이드](/blog/proxmox-alerts)를 참고하세요. 다른 연동이 필요하다면 [웹훅 알림](/use-cases/webhook-notifications)과 [Grafana 알림](/use-cases/grafana-alerts)을 보세요. 여러 옵션을 비교하고 있다면 [대안 페이지](/alternatives)에서 차이점을 정리해 두었어요.
