# 푸시 알림 API란 무엇이며, 언제 필요할까요?

> 푸시 알림 API는 HTTP 요청 한 번을 기기의 알림으로 바꿔 줍니다. 무엇을 하는지, 같은 이름을 쓰는 두 종류의 제품, 요청의 모습, 그리고 고르기 전에 확인할 점을 정리했습니다.

*04.10.2026*

<!-- source: https://pocketalert.app/ko/blog/what-is-a-push-notification-api -->

푸시 알림 API는 코드가 요청하면 휴대폰 잠금 화면에 메시지를 띄워 주는 웹 서비스입니다. 제목과 본문을 담아 HTTP 요청을 한 번 보내면, 서비스가 이를 Apple이나 Google에 전달하고, 앱이 실행 중이든 아니든 몇 초 안에 휴대폰에 알림이 표시됩니다.

이게 핵심 개념의 전부입니다. 세부 사항은 알림을 누가 받는지, 그리고 전달 과정의 어느 부분까지 직접 맡고 싶은지에 달려 있습니다.

## 같은 이름을 쓰는 두 가지 다른 것

"푸시 알림 API"를 검색하면 거의 겹치지 않는 두 종류의 제품이 나옵니다.

**사용자에게 푸시하는 플랫폼.** Firebase Cloud Messaging, Apple Push Notification service, OneSignal 등이 여기에 속합니다. 모바일 앱을 직접 만들어 App Store와 Google Play에 배포하고, 설치된 기기마다 기기 토큰을 수집해서 수천 명에게 제품 또는 마케팅 알림을 보냅니다. 이 API는 긴 프로젝트의 마지막 단계입니다.

**나에게 푸시하는 서비스.** Pocket Alert, Pushover, ntfy 등이 여기에 속합니다. 앱은 이미 있습니다. 내 휴대폰에 설치하고 API 키를 발급받은 뒤, 스크립트, 서버, 다른 서비스에서 알림을 보내면 됩니다. 앱을 배포할 필요도, 토큰을 수집할 필요도 없습니다. 배포가 끝났을 때, 백업이 실패했을 때, 결제가 들어왔을 때 바로 알림을 받습니다.

이 가이드는 두 번째 종류에 관한 것입니다. 소비자용 앱을 만들어서 그 사용자들에게 닿아야 한다면 첫 번째 종류가 필요하고, 아래 내용의 대부분은 해당하지 않습니다.

## 요청을 보내면 무슨 일이 일어날까요

네 단계를 거치며, 대부분은 눈에 보이지 않습니다.

1. 코드가 제목, 메시지, API 키를 담아 서비스에 HTTPS 요청을 보냅니다.
2. 서비스는 키를 확인하고 메시지를 저장한 뒤, 어디로 보낼지 결정합니다. 내 기기 중 어느 기기로, 어떤 우선순위로 보낼지 정합니다.
3. 서비스는 알림을 플랫폼 고유의 푸시 네트워크에 넘깁니다. iPhone은 APNs, Android는 Firebase Cloud Messaging을 사용합니다.
4. Apple이나 Google은 모든 휴대폰이 이미 유지하고 있는 연결을 통해 알림을 전달하고, 휴대폰에 표시됩니다.

3단계와 4단계 덕분에 앱이 닫혀 있어도 푸시가 작동하고, 배터리도 거의 소모되지 않습니다. 휴대폰이 누구에게도 계속 물어보지 않기 때문입니다. 전체 경로는 [푸시 알림 작동 원리: APNs와 FCM](/blog/how-push-notifications-work-apns-fcm)에서 자세히 볼 수 있습니다.

## 왜 Apple과 Google에 직접 연결하지 않을까요?

양쪽 스토어에 내 앱이 있다면 직접 연결할 수도 있습니다. 중간에 아무것도 없이 내 휴대폰으로 푸시하려면 다음이 필요합니다.

- Apple Developer Program 멤버십과 푸시 권한이 설정된 iOS 앱, 그리고 나머지 절반인 Firebase 프로젝트와 Android 앱.
- APNs 서명 키와 Firebase 서비스 계정, 그리고 각각에 맞게 요청에 서명하는 코드.
- 앱에서 기기 토큰을 수집하고, 토큰이 바뀔 때마다 최신 상태로 유지하는 방법.
- 요청 형식 두 가지, 우선순위 모델 두 가지, 오류 코드 두 세트.

앱이 제품 자체라면 이 작업은 합리적인 프로젝트입니다. 하지만 "크론 작업이 실패하면 알려 줘" 정도를 위해서라면 지나치게 복잡합니다. 푸시 알림 서비스가 이 모든 작업을 모든 사용자를 위해 한 번에 처리해 두었습니다.

## 요청은 이런 모습입니다

Pocket Alert에서 알림을 보내려면 인증된 POST 요청 하나면 됩니다.

```bash
curl -X POST https://api.pocketalert.app/v1/messages \
  -H 'Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Deploy finished", "message": "api v2.4.1 is live"}'
```

응답은 저장된 메시지와 발송된 우선순위를 담은 `201 Created`입니다. HTTP 클라이언트를 쓸 수 있는 언어라면 어디서든 같은 요청을 보낼 수 있고, [curl로 푸시 알림 보내기](/use-cases/curl-push-notifications)에서 터미널 예제를 더 볼 수 있습니다.

필수 항목은 `title`과 `message`뿐입니다. 알림에서 특히 중요한 선택 항목은 다음과 같습니다.

- `level`은 알림이 얼마나 강하게 울릴지 정합니다. `silent`, `low`, `default`, `high`, `critical` 중에서 고를 수 있습니다.
- `actions`는 알림에 최대 세 개의 버튼을 추가합니다. URL 열기, HTTP 요청 실행, 값 복사 중에서 고를 수 있습니다.
- `send_at` 또는 `delay`는 지금이 아니라 나중에 보내도록 합니다(유료 플랜).
- `application_id`와 `device_id`는 알림이 어느 프로젝트에 속하는지, 그리고 어느 휴대폰으로 가는지 지정합니다.

## API만이 아닌 세 가지 입력 경로

푸시 알림 API는 모든 출처마다 코드를 따로 작성하지 않아도 될 때 가장 유용합니다.

- **HTTP API**는 내 스크립트, 작업, 앱에서 사용합니다.
- **웹훅 URL**은 이미 웹훅을 보내는 서비스에서 사용합니다. GitHub, Stripe, Grafana, Sentry는 자체 JSON을 Pocket Alert 웹훅으로 보낼 수 있고, `%repository.name%` 같은 자리표시자가 그 안의 필드를 골라 알림에 넣어 줍니다. 중간에 코드가 필요 없습니다. [첫 웹훅 URL 만들기](/blog/create-your-first-webhook-url)에서 단계별로 설명합니다.
- **CLI와 MCP 서버**는 터미널과 AI 에이전트를 위한 것입니다. 셸에서 `pocketalert send "Build done" "All tests passed"`를 실행하거나([CLI](/tools/cli)), 긴 작업이 끝날 때 Claude나 Cursor가 호출하는 `create_message` 도구를 사용할 수 있습니다([MCP](/tools/mcp)).

## 어디에 쓸 수 있을까요

대부분의 알림은 몇 가지 유형으로 나뉩니다.

- **무언가 고장 났을 때.** 서버가 응답을 멈추었거나, 크론 작업이 0이 아닌 값으로 종료되었거나, 백업이 실행되지 않았을 때입니다. [크론 작업 알림](/use-cases/cron-job-alerts)과 [서버 모니터링](/use-cases/server-monitoring)을 참고하세요.
- **무언가 끝났을 때.** 배포, 오래 걸리는 빌드, 12시간짜리 3D 프린트, AI 에이전트의 작업이 여기에 해당합니다. [배포 알림](/use-cases/deployment-alerts)을 참고하세요.
- **중요한 일이 생겼을 때.** 결제, 회원가입, 폼 제출이 여기에 해당합니다. [결제 알림](/use-cases/payment-alerts)과 [회원가입 알림](/use-cases/signup-alerts)을 참고하세요.
- **곧 일어날 일이 있을 때.** 14일 뒤 만료되는 인증서가 여기에 해당합니다. [SSL 만료 알림](/use-cases/ssl-expiration-alerts)을 참고하세요.

공통점은 누군가 지금 바로 알아야 할 사건이라는 것입니다. 대시보드나 받은편지함을 다음에 열 때까지 기다릴 일이 아닙니다.

## 고르기 전에 확인할 것

이 분야의 모든 서비스는 HTTP 요청으로 푸시를 보냅니다. 차이는 그 주변에 있습니다.

- **플랫폼.** 일부는 iPhone 전용입니다(Bark, The Notification App). Gotify의 공식 앱은 Android용뿐입니다. 알림을 받아야 하는 사람이 다른 기종의 휴대폰을 쓴다면 그것만으로 결정될 수 있습니다.
- **우선순위 수준.** 실패한 백업과 새 회원가입이 다른 소리로 울릴 수 있나요? 긴급 알림이 방해 금지 모드를 뚫고 올 수 있나요?
- **수신 웹훅.** 서비스가 자체 JSON을 그대로 보낼 수 있나요, 아니면 모든 출처마다 스크립트로 형식을 바꿔야 하나요?
- **기록과 로그.** 알림이 도착하지 않았을 때, 호출 기록과 그 이후 과정을 확인할 수 있나요?
- **한도와 요금.** 하루, 한 달, 또는 평생 기준인가요? 한도에 도달하면 어떻게 되나요?
- **운영 주체.** 호스팅 서비스인가요, 아니면 직접 관리하는 서버인가요?

[대안](/alternatives)에서는 Pocket Alert를 Pushover, ntfy, Pushbullet, Bark, Gotify 등과 이 기준들로 비교하고, 각 서비스가 더 나은 선택이 되는 경우도 함께 설명합니다.

## 자주 묻는 질문

### 푸시 알림 API는 Firebase Cloud Messaging과 같은 것인가요?

FCM도 푸시 알림 API 중 하나입니다. 직접 만들어 배포하는 앱을 위해 Google이 제공하는 API죠. Pocket Alert 같은 서비스는 FCM과 APNs 위에서 동작하며, 앱, 키, 기기 토큰을 대신 관리해 주므로 사용자는 HTTP 요청만 만들면 됩니다.

### 모바일 앱을 직접 만들어야 하나요?

나 자신이나 팀에게 알림을 보내는 데는 필요 없습니다. [iPhone 또는 Android](/get-app)용 Pocket Alert처럼 기존 앱을 설치하고 그 앱으로 보내면 됩니다. 나만의 앱은 내 사용자에게 푸시할 때만 필요합니다.

### 무료인가요?

많은 서비스에 무료 플랜이 있습니다. Pocket Alert의 무료 플랜은 카드 등록 없이 하루 50건을 보낼 수 있어서 개인 알림 대부분을 감당할 수 있습니다. 유료 플랜은 월 $6부터 시작하며 하루 1,000건까지 보낼 수 있습니다. 자세한 내용은 [요금 페이지](/pricing)에서 확인하세요.

### 전달은 얼마나 빠른가요?

보통 요청부터 잠금 화면까지 몇 초 정도 걸립니다. 다만 Apple과 Google은 시간을 보장하지 않습니다. 신호가 없는 휴대폰이나 배터리 절약 모드가 강하게 켜진 휴대폰은 다시 연결될 때 알림을 받습니다.

### 푸시, SMS, 이메일 중 무엇을 써야 하나요?

지금 주의가 필요한 일에는 푸시를, 요약과 기록에는 이메일을, 스마트폰 앱이 전혀 없는 사람에게는 SMS를 쓰세요. 장단점은 [푸시 알림 vs SMS](/blog/push-notifications-vs-sms)와 [푸시 알림 vs 이메일 알림](/blog/push-vs-email-alerts)에서 다룹니다.

[무료 계정 만들기](/signup)를 하고 API 키를 복사한 다음, 위의 curl 명령을 실행하면 첫 번째 푸시 알림을 보낼 수 있습니다.
