# Klipper 푸시 알림: 출력 상태를 휴대폰으로 받아보기

> Klipper 출력이 끝나거나, 실패하거나, 일시 정지되면 푸시 알림을 받으세요. Moonraker에 내장된 알림 기능과 Pocket Alert 웹훅으로, 플러그인 없이 설정 블록 하나면 충분합니다.

*09.10.2026*

<!-- source: https://pocketalert.app/ko/blog/klipper-print-notifications -->

열두 시간짜리 출력을 옆에서 지켜볼 필요는 없어요. 필요한 건 출력이 끝나는 순간, 그리고 더 중요하게는 출력이 멈추는 순간을 아는 것입니다.

Klipper는 이 두 가지를 이미 알려줄 수 있어요. Mainsail과 Fluidd의 뒤에서 동작하는 API 서버인 Moonraker에는 출력 이벤트에 반응해 [Apprise](https://github.com/caronc/apprise)로 알림을 보내는 기능이 내장되어 있습니다. 이 기능이 Pocket Alert 웹훅을 가리키게 하면, 완료되거나, 실패하거나, 취소되거나, 일시 정지된 모든 출력이 휴대폰 푸시 알림으로 도착해요. 플러그인도, 라즈베리 파이에 추가로 올릴 서비스도 필요 없고, 설정 블록 하나면 끝납니다.

## 준비물

- Moonraker가 설치된 Klipper 프린터. 브라우저에서 Mainsail이나 Fluidd를 열 수 있다면 Moonraker가 있는 거예요.
- 무료 [Pocket Alert](/) 계정과 [iPhone 또는 Android](/get-app) 휴대폰의 앱.
- 약 5분.

## 1단계. Pocket Alert에서 웹훅 만들기

대시보드에서 [웹훅](/webhooks)을 열고 새 웹훅을 만드세요:

- **이름** – 프린터 이름, 예를 들어 `Voron 2.4`. 이 이름이 푸시 제목(`Webhook Voron 2.4`)이 되므로 프린터가 여러 대라면 어느 프린터가 도움을 필요로 하는지 한눈에 알 수 있어요.
- **애플리케이션**과 **기기** – 알림이 전달될 위치.
- **메시지** – 다음 템플릿을 붙여넣으세요:

```
%title%
%message%
```

저장한 뒤 웹훅 URL을 복사하세요. 형태는 `https://p4a.me/wh/<your-webhook-id>`와 같아요.

이 템플릿을 쓰는 이유: Moonraker는 각 알림을 Apprise에 넘기고, Apprise의 JSON 알림 기능은 아래와 같은 작은 페이로드를 전송합니다:

```json
{
  "version": "1.0",
  "title": "❌ Print error",
  "message": "3DBenchy.gcode Move out of range: 235.000 0.000 0.200 [0.000]",
  "attachments": [],
  "type": "info",
  "level": "high"
}
```

템플릿의 `%key%`는 JSON에서 해당 필드 값으로 바뀝니다. 푸시에서는 첫 줄에 제목이, 그 아래에 메시지가 표시돼요. 템플릿 경로에 대한 자세한 내용은 [첫 웹훅 URL 만들기](/blog/create-your-first-webhook-url)에서 확인하세요.

## 2단계. moonraker.conf에 알림 설정 추가하기

`moonraker.conf`를 여세요. Mainsail에서는 **Machine**, Fluidd에서는 **Configuration** 아래에 있어요. 그리고 파일 끝에 다음 세 섹션을 추가하세요. `YOUR_WEBHOOK_ID`는 웹훅 URL에 있는 ID로 바꿔 주세요.

```ini
[notifier pocketalert_done]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID
events: complete
title: ✅ Print complete
body: {event_args[1].filename}

[notifier pocketalert_fail]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID?:level=high
events: error, cancelled
title: ❌ Print {event_name}
body: {event_args[1].filename} {event_args[1].message}

[notifier pocketalert_pause]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID?:level=high
events: paused
title: ⏸ Print paused
body: {event_args[1].filename}: check the printer
```

각 항목의 역할:

- **`jsons://`**는 HTTPS로 동작하는 Apprise의 JSON 알림 기능이에요. 위의 페이로드를 웹훅으로 보냅니다.
- **`events`**는 섹션을 트리거할 출력 상태를 고릅니다. Moonraker는 `started`, `complete`, `error`, `cancelled`, `paused`, `resumed`를 지원해요.
- **`?:level=high`**는 Apprise가 JSON에 `"level": "high"`를 추가하도록 합니다. Pocket Alert는 이 필드를 읽고 높은 우선순위로 푸시를 보내요. iPhone에서는 시간에 민감한 알림으로 도착해 집중 모드도 뚫고 들어옵니다. "complete" 섹션에는 level이 없으므로 일반 푸시로 도착해요.
- **`{event_args[1]}`**는 이벤트 이후의 출력 작업 상태예요. Klipper의 `print_stats` 객체와 같아서, `filename`은 G-code 파일이고 `message`는 출력이 실패했을 때 Klipper가 남긴 오류 텍스트예요.
- **`{event_name}`**은 발생한 이벤트예요. 그래서 하나의 섹션이 `error`와 `cancelled`를 모두 처리하면서도 제목에서 어떤 일이 일어났는지 알려 줍니다.

## 3단계. Moonraker 재시작 후 테스트하기

Mainsail이나 Fluidd의 전원 메뉴에서 Moonraker를 재시작하거나, SSH로 다음 명령을 실행하세요:

```bash
sudo systemctl restart moonraker
```

테스트로 필라멘트를 쓰기 전에 curl로 웹훅을 먼저 확인하세요. Apprise가 보내는 것과 같은 형태의 JSON을 전송합니다:

```bash
curl -X POST https://p4a.me/wh/YOUR_WEBHOOK_ID \
  -H 'Content-Type: application/json' \
  -d '{"title":"❌ Print error","message":"test.gcode Move out of range","level":"high"}'
```

휴대폰이 진동하면 Pocket Alert 쪽은 정상이에요. 이제 작은 출력을 시작하고 첫 레이어 뒤에 취소해 보세요. 몇 초 안에 `❌ Print cancelled` 알림이 와야 합니다.

## 휴대폰에 도착하는 알림

밤에 출력이 실패하면 잠금 화면에는 이렇게 보입니다:

```
Webhook Voron 2.4
❌ Print error
3DBenchy.gcode Move out of range: 235.000 0.000 0.200 [0.000]
```

휴대폰 잠금을 풀기 전에 어느 프린터인지, 어떤 파일인지, 왜 멈췄는지 알 수 있어요.

## 내 환경에 맞게 바꾸기

아래 내용은 모두 같은 파일을 조금 수정하는 것입니다.

- **출력 시작은 조용히 기록하기.** `events: started`와 `?:level=silent`를 넣은 섹션을 추가하세요. 시작 기록은 소리 없이 메시지 기록에 남아요.
- **실패하면 바로 깨우기.** 실패 섹션의 `?:level=high`를 `?:level=critical`로 바꾸세요. Android에서는 critical 알림이 방해 금지 모드를 뚫고 들어와요. Critical 전달은 유료 기능이라, 무료 플랜에서는 메시지가 여전히 high 우선순위로 도착합니다. 자세한 내용은 [critical 알림](/use-cases/critical-alerts)을 참고하세요.
- **프린터가 여러 대일 때.** 프린터마다 웹훅을 하나씩 만들고, 각 웹훅 이름을 장비 이름으로 지어 주세요. 푸시 제목을 보면 어느 프린터가 멈췄는지 알 수 있어요.
- **직접 만든 매크로에서 알림 보내기.** Moonraker에는 `gcode` 이벤트도 있어서, Klipper 매크로로 원하는 텍스트를 보낼 수 있어요. 필라멘트 교체나 런아웃 센서에 유용합니다.

`moonraker.conf`에 추가:

```ini
[notifier pocketalert_macro]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID?:level=high
events: gcode
title: 🧵 Printer needs you
body: {event_message}
```

`printer.cfg`에 추가:

```ini
[gcode_macro NOTIFY_FILAMENT_CHANGE]
gcode:
  {action_call_remote_method("notify",
                             name="pocketalert_macro",
                             message="Filament change needed")}
```

`NOTIFY_FILAMENT_CHANGE` 매크로나 필라멘트 센서의 `M600`에서 `runout_gcode`를 호출하세요.

## 알림이 도착하지 않는다면

- **대시보드에서 웹훅 확인하기.** [웹훅 기록](/features/webhook-history)에는 모든 호출과 원본 페이로드가 남아요. 기록이 없다면 Moonraker가 Pocket Alert에 도달하지 못한 거예요. 오류가 있는 기록이 있다면 그 이유가 적혀 있어요.
- **`moonraker.log` 읽기.** Moonraker는 알림 오류를 설치된 Apprise 버전과 함께 이 파일에 기록해요. 대부분의 설치에서는 `~/printer_data/logs/moonraker.log`에 있습니다.
- **푸시에 빈 줄이 보일 때.** 템플릿 키는 Apprise 페이로드와 맞아야 해요. `%title%`가 아니라 `%message%`과 `%body%`를 써야 합니다.

## 왜 플러그인이 아닌가요?

Klipper용 텔레그램 봇이나 원격 접속 서비스는 카메라 스냅샷, 타임랩스, 원격 제어처럼 더 많은 기능을 제공해요. 대신 라즈베리 파이에 설치하고 계속 업데이트해야 하는 서비스가 하나 더 생기죠. "끝나면 알려 주고, 실패하면 깨워 줘"가 목표라면 Moonraker가 이미 알림을 보내고 있으니, Pocket Alert는 받기만 하면 됩니다.

프린터가 [홈랩](/use-cases/homelab-alerts) 옆에 있다면, 프린터 알림도 서버, 백업, 크론 작업 알림과 같은 앱에 모이고 같은 기록과 같은 우선순위 단계를 따릅니다.

## 자주 묻는 질문

### 라즈베리 파이에 무언가 설치해야 하나요?

아니요. 알림 기능은 Moonraker에 포함되어 있고, Apprise는 의존성으로 함께 설치돼요. `moonraker.conf`를 수정하고 Moonraker를 재시작하기만 하면 됩니다.

### Mainsail과 Fluidd에서도 동작하나요?

네. 둘 다 Moonraker의 웹 인터페이스이고, 알림 기능은 Moonraker에 있으므로 설정 방법이 같아요. 둘 중 어디서든 `moonraker.conf`를 수정할 수 있습니다.

### 프린터 여러 대의 알림을 받을 수 있나요?

네. 프린터마다 웹훅을 하나씩 만들고 장비 이름으로 지으세요. 웹훅 이름이 푸시 제목이 됩니다.

### 실패한 출력이 밤에 나를 깨울까요?

`level=high`를 쓰면 iPhone에서 시간에 민감한 알림으로 도착해 집중 모드도 뚫고 들어와요. Android에서 방해 금지 모드를 뚫으려면 유료 플랜에서 `level=critical`을 사용하세요.

### 무료인가요?

네. 웹훅은 무료 플랜에서도 쓸 수 있어요. 이벤트마다 일일 한도에서 메시지 하나를 사용하고, 일반적인 출력은 한두 개의 메시지를 보냅니다.

[웹훅 만들기](/webhooks)에서 설정을 붙여넣으세요. 다음 출력부터는 끝나는 순간을 바로 알려 줄 거예요.
