# Stripe 결제 알림: 판매, 결제 실패, 분쟁마다 휴대폰 푸시 알림

> Stripe 웹훅을 Pocket Alert에 연결하면 결제, 결제 실패, 분쟁, 신규 구독마다 푸시 알림을 받아요. 기본 설정은 코드 없이, 금액 서식과 서명 검증은 Node 약 60줄로 할 수 있어요.

*20.10.2026*

<!-- source: https://pocketalert.app/ko/blog/stripe-payment-notifications -->

하루 첫 판매 소식은 꼭 듣고 싶으시죠. 새벽 2시에 실패한 정기 결제는 더 중요하고, 분쟁에는 기한이 있어요. 기한 안에 응답하지 않으면 그 건을 잃게 돼요. Stripe는 세 가지 모두 일어나는 순간 알고 있어요. 그런데 대시보드를 다시 열어 보기 전까지는 모르고 지나가기 쉬워요.

Stripe에도 자체 알림 기능이 있어요. iOS와 Android의 Stripe 대시보드 앱은 새 결제, 신규 고객, 분쟁 결제, 입금 완료, 일일 요약을 푸시 알림으로 보내 주고, 대시보드에서는 계정 이벤트를 이메일로 받을 수 있어요. 이것만으로도 많은 부분을 다룰 수 있어요. 다만 알림을 직접 제어하기는 어려워요. 문구를 바꿀 수 없고, 결제 실패 알림을 판매 알림보다 강하게 울리게 할 수도 없고, 자체 시스템에서 생기는 이벤트를 같은 피드로 보낼 수도 없어요. Stripe에서 [Pocket Alert](/use-cases/payment-alerts)로 보내는 웹훅을 쓰면 이 모든 것이 가능해요.

## 준비물

- 웹훅을 만들 권한이 있는 Stripe 계정(Administrator 또는 Developer 역할).
- Pocket Alert 계정, [API 키](/account/apikeys), 그리고 [iPhone 또는 Android](/get-app)에 설치한 앱.
- 코드 방식을 쓸 경우 Node 20 이상과 외부에서 접근 가능한 실행 환경.

## 1단계: 코드 없이 설정하기

Stripe는 모든 이벤트를 JSON으로 보내고, [Pocket Alert 웹훅](/tools/webhook)은 JSON을 받아 템플릿으로 렌더링해요. 이 작업에 필요한 연결은 그게 전부예요.

### 1. 이벤트 종류마다 Pocket Alert 웹훅 하나씩 만들기

이벤트 종류별로 웹훅을 하나씩 만드는 것이 핵심이에요. 푸시 알림 제목은 항상 `Webhook <name>`이 되므로, 웹훅 이름이 잠금 화면에서 보이는 내용을 결정해요. 웹훅마다 기본 우선순위와 버튼을 따로 설정할 수 있어요. 무료 플랜에는 웹훅이 하나 포함되어 있으니 판매 알림부터 시작하세요. 네 가지를 모두 쓰려면 유료 [플랜](/pricing)이 필요하고, 액션 버튼도 유료 플랜에서 사용할 수 있어요.

웹훅은 [웹훅](/webhooks) 콘솔에서 만들 수 있어요. 이름, 템플릿, 기본 우선순위를 설정할 수 있어요. 액션 버튼은 API로 설정하므로, 웹훅마다 curl 명령을 한 번씩 실행하면 한꺼번에 설정할 수 있어요.

```bash
export PA_KEY='YOUR_API_KEY'

curl -sS https://api.pocketalert.app/v1/webhooks \
  -H "Token: $PA_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'EOF'
{
  "name": "Stripe sale",
  "message": "%data.object.amount_total% %data.object.currency% from %data.object.customer_details.email% (%data.object.payment_status%)",
  "default_level": 0,
  "actions": "[{\"type\":\"view\",\"label\":\"Open in Stripe\",\"value\":\"https://dashboard.stripe.com/payments/%data.object.payment_intent%\"}]"
}
EOF
```

응답에는 `url` 슬러그가 들어 있어요. 수신 URL은 `https://p4a.me/wh/<slug>`이고, 콘솔에서도 확인할 수 있어요. `actions`는 배열이 아니라 JSON 문자열이라서 따옴표를 이스케이프했어요.

나머지 세 개도 아래 본문으로 같은 방식으로 만드세요.

```json
{
  "name": "Stripe payment failed",
  "message": "%data.object.amount_due% %data.object.currency% failed for %data.object.customer_email%, attempt %data.object.attempt_count%",
  "default_level": 1,
  "actions": "[{\"type\":\"view\",\"label\":\"Open invoice\",\"value\":\"https://dashboard.stripe.com/invoices/%data.object.id%\"},{\"type\":\"copy\",\"label\":\"Copy pay link\",\"value\":\"%data.object.hosted_invoice_url%\"}]"
}
```

```json
{
  "name": "Stripe dispute",
  "message": "%data.object.amount% %data.object.currency% disputed. Reason: %data.object.reason%",
  "default_level": 2,
  "actions": "[{\"type\":\"view\",\"label\":\"Open payment\",\"value\":\"https://dashboard.stripe.com/payments/%data.object.payment_intent%\"}]"
}
```

```json
{
  "name": "Stripe subscription",
  "message": "New %data.object.status% subscription: %data.object.items.data.0.price.unit_amount% %data.object.currency% per %data.object.items.data.0.price.recurring.interval%",
  "default_level": -1,
  "actions": "[{\"type\":\"view\",\"label\":\"Open subscription\",\"value\":\"https://dashboard.stripe.com/subscriptions/%data.object.id%\"}]"
}
```

우선순위는 `-2`(무음)에서 `2`(치명적)까지 있어요. 결제 실패는 `high`로 설정해서 iPhone의 집중 모드에서도 알림이 울리게 했어요. 분쟁은 `critical`로 설정해서 무음 스위치와 방해 금지 모드에서도 소리가 나요. 치명적 알림은 유료 플랜에서만 쓸 수 있고, 무료 플랜에서는 `high`로 전달돼요. 신규 구독은 `low`로 설정했어요. 알아두면 좋지만 진동을 울릴 만큼은 아니에요.

결제 실패 푸시의 복사 버튼을 누르면 인보이스의 결제 페이지 링크가 클립보드에 복사돼요. "카드가 거절되었습니다" 같은 안내 메일에 바로 붙여 넣을 수 있어요.

### 2. Stripe에서 이벤트 대상 추가하기

Stripe 대시보드에서 **Workbench**를 열고 **Webhooks** 탭으로 이동한 다음 **Create an event destination**을 클릭하세요. 그다음 아래 순서대로 진행하세요.

1. **Your account**를 선택하세요.
2. **Snapshot** 페이로드를 선택하세요. Stripe는 새 코드에는 Thin을 권장하지만, Thin 이벤트에는 객체 ID만 들어 있어서 템플릿에 보여 줄 금액이나 이메일이 없어요. Snapshot은 전체 객체를 보내요.
3. 이벤트를 선택하세요. 예를 들어 `checkout.session.completed`를 고르면 돼요.
4. 대상 유형으로 **Webhook endpoint**를 고르고, 해당하는 `https://p4a.me/wh/...` URL을 붙여 넣으세요.

Pocket Alert 웹훅 하나당 이 과정을 한 번씩 하세요. 각 Stripe 대상은 이벤트 종류 하나를 URL 하나로 보내도록 구성해요.

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Stripe 이벤트</th><th>Pocket Alert 웹훅</th><th>푸시 제목</th><th>우선순위</th></tr></thead>
<tbody>
<tr><th><code>checkout.session.completed</code></th><td>Stripe sale</td><td>Webhook Stripe sale</td><td>default</td></tr>
<tr><th><code>invoice.payment_failed</code></th><td>Stripe payment failed</td><td>Webhook Stripe payment failed</td><td>high</td></tr>
<tr><th><code>charge.dispute.created</code></th><td>Stripe dispute</td><td>Webhook Stripe dispute</td><td>critical</td></tr>
<tr><th><code>customer.subscription.created</code></th><td>Stripe subscription</td><td>Webhook Stripe subscription</td><td>low</td></tr>
</tbody>
</table>
</div>

Stripe는 계정당 이벤트 대상을 16개까지 허용하므로 네 개면 충분해요.

**Checkout인가요, PaymentIntents인가요?** 고객이 Checkout이나 Payment Links로 결제한다면 `checkout.session.completed`를 쓰세요. 직접 결제 폼을 만들었다면 대신 `payment_intent.succeeded`를 쓰고, 템플릿을 `%data.object.amount% %data.object.currency% %data.object.receipt_email%`로, 버튼 경로를 `/payments/%data.object.id%`로 바꾸세요. 두 이벤트를 모두 구독하면 판매 한 건당 푸시가 두 번 와요. Checkout 결제에서는 두 이벤트가 모두 발생하기 때문이에요.

### 3. 테스트하기

샌드박스에서 테스트 결제를 만들거나, Stripe CLI로 `stripe trigger checkout.session.completed`를 실행하세요. 그다음 Pocket Alert 콘솔에서 해당 웹훅을 여세요. 기록에는 Stripe가 보낸 모든 요청이 헤더, 원본 본문, 렌더링된 메시지, 응답 상태와 함께 표시돼요. 값이 비어 나오는 필드가 있다면 어느 경로가 잘못됐는지 여기서 바로 확인할 수 있어요.

판매 알림은 이렇게 도착해요.

```text
Webhook Stripe sale
4900 usd from alex@example.com (paid)
[Open in Stripe]
```

## 템플릿으로 할 수 없는 것

의존하기 전에 한계를 분명히 알아 두세요.

- **금액은 최소 단위로 와요.** Stripe는 49.00달러를 `4900`으로, 엔화 5,000엔을 `5000`으로 보내요. 엔화에는 소수점 단위가 없기 때문이에요. 템플릿은 값을 그대로 복사하고 100으로 나눌 수 없어요. `4900 usd`는 금방 읽는 데 익숙해지겠지만, `$49.00`처럼 보이게 하려면 2단계를 쓰세요.
- **서명 검증이 없어요.** Stripe는 각 요청에 `Stripe-Signature` 헤더로 서명을 붙여요. Pocket Alert는 외부 서명을 검증하지 않아요. URL에 들어 있는 임의 슬러그가 유일한 비밀이에요. 이 URL을 아는 사람은 가짜 "판매" 알림을 보낼 수 있어요. 알림만 오는 것이라 번거로움 정도이고 실제 결제 처리가 일어나지는 않아요. 그래도 URL은 비공개로 관리하고, 푸시가 Stripe에서 온 것인지 증명해야 한다면 2단계를 쓰세요.
- **조건을 걸 수 없어요.** 템플릿으로 "500달러 이상 판매만 알림" 또는 "테스트 모드는 건너뛰기" 같은 조건은 설정할 수 없어요. 필터링은 선택한 이벤트로 Stripe에서 하거나 코드로 해야 해요.
- **대시보드 버튼은 라이브 모드를 가리켜요.** 테스트 객체는 `dashboard.stripe.com/test/...` 아래에 있으므로, 테스트 모드 이벤트에서 버튼을 누르면 존재하지 않는 페이지가 열려요. 레거시 Charges API의 분쟁에는 `payment_intent`가 없어서 해당 버튼의 링크가 비어 있어요.
- **구독은 첫 번째 가격만 보여요.** `items.data.0`은 첫 번째 항목이에요. 이벤트에는 이메일이 아니라 고객 ID가 들어 있어요.
- **모든 이벤트가 일일 한도에 포함돼요.** 무료 플랜은 하루 50건까지 보낼 수 있어요. 한도를 넘으면 Pocket Alert는 `429`를 응답하고, Stripe는 이를 전송 실패로 보고 라이브 모드에서는 최대 3일 동안 재시도해요.

## 2단계: 서명을 검증하는 작은 핸들러

실제 통화 서식, 서명 검증, 모든 이벤트를 받는 엔드포인트 하나가 필요하면 Stripe와 Pocket Alert 사이에 Node 코드 약 60줄을 두세요. 서명 검증에는 Stripe 공식 라이브러리를 쓰고, 푸시 전송에는 `POST /v1/messages`를 써요.

```bash
npm install express stripe
```

```js
// server.mjs
import express from 'express';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();

function money(minor, currency) {
  const fmt = new Intl.NumberFormat('en-US', { style: 'currency', currency: currency.toUpperCase() });
  return fmt.format(minor / 10 ** fmt.resolvedOptions().maximumFractionDigits);
}

function toPush(event) {
  const o = event.data.object;
  switch (event.type) {
    case 'checkout.session.completed':
      return { title: `Sale ${money(o.amount_total, o.currency)}`, level: 'default',
        message: `${o.customer_details?.email ?? 'no email'} · ${o.payment_status}`,
        path: o.payment_intent ? `payments/${o.payment_intent}` : `customers/${o.customer}` };
    case 'invoice.payment_failed':
      return { title: `Payment failed ${money(o.amount_due, o.currency)}`, level: 'high',
        message: `${o.customer_email ?? o.customer} · attempt ${o.attempt_count}`,
        path: `invoices/${o.id}` };
    case 'charge.dispute.created':
      return { title: `Dispute ${money(o.amount, o.currency)}`, level: 'critical',
        message: `Reason: ${o.reason}. Evidence due ${new Date(o.evidence_details.due_by * 1000).toDateString()}`,
        path: `payments/${o.payment_intent ?? o.charge}` };
    case 'customer.subscription.created': {
      const price = o.items.data[0]?.price;
      return { title: 'New subscription', level: 'low',
        message: price?.unit_amount != null
          ? `${money(price.unit_amount, price.currency)} per ${price.recurring?.interval} · ${o.status}`
          : o.status,
        path: `subscriptions/${o.id}` };
    }
  }
  return null;
}

app.post('/stripe-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = stripe.webhooks.constructEvent(req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET);
  } catch (err) {
    return res.status(400).send(`Bad signature: ${err.message}`);
  }
  res.sendStatus(200);

  const push = toPush(event);
  if (!push) return;
  const dashboard = event.livemode ? 'https://dashboard.stripe.com/' : 'https://dashboard.stripe.com/test/';

  await fetch('https://api.pocketalert.app/v1/messages', {
    method: 'POST',
    headers: { Token: process.env.POCKETALERT_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      title: push.title,
      message: push.message,
      level: push.level,
      actions: [{ type: 'view', label: 'Open in Stripe', value: dashboard + push.path }],
    }),
  }).catch((err) => console.error('Pocket Alert:', err.message));
});

app.listen(process.env.PORT ?? 4242);
```

```bash
STRIPE_SECRET_KEY=sk_live_... STRIPE_WEBHOOK_SECRET=whsec_... POCKETALERT_KEY=... node server.mjs
```

중요한 부분은 다음과 같아요.

- `express.raw`는 본문을 바이트 그대로 보관해요. `constructEvent`는 Stripe가 보낸 요청 그대로를 필요로 하고, JSON 본문 파서를 거치면 서명이 깨져요. 또한 5분보다 오래된 이벤트는 거부해서 재전송 공격을 막아요.
- 핸들러는 Pocket Alert를 호출하기 전에 `200`을 먼저 응답해요. Stripe는 빠른 `2xx` 응답을 기대하기 때문이에요. `STRIPE_SECRET_KEY`는 읽기 권한만 있는 제한 키로도 충분해요. 이 코드는 Stripe API를 호출하지 않아요.
- `Intl.NumberFormat`은 통화마다 소수점 자릿수를 알고 있어요. 그래서 `4900 usd`는 `$49.00`이 되고, `5000 jpy`는 `¥5,000`이 돼요.
- `livemode` 플래그로 올바른 대시보드 경로를 골라서, 테스트 모드 이벤트는 테스트 모드 페이지를 열어요.

Stripe에서 **Snapshot** 페이로드, 네 가지 이벤트, 서버 URL을 모두 넣은 이벤트 대상을 하나 만드세요. 그다음 대상 페이지에서 `whsec_`로 시작하는 서명 시크릿을 복사하세요. 로컬에서 테스트하려면 `stripe listen --forward-to localhost:4242/stripe-webhook`을 실행해 사용할 시크릿을 확인하고, `stripe trigger invoice.payment_failed`로 서명된 테스트 이벤트를 보내세요.

휴대폰에는 "Sale $49.00" 제목에 "alex@example.com · paid"가 아래에 표시된 푸시가 도착해요. 분쟁 알림은 본문에 기한이 적혀 있어서 바로 확인하게 해 줘요.

판매와 회원가입을 한 피드에서 함께 보고 싶으신가요? 회원가입 폼도 같은 앱으로 보내도록 [회원가입 알림](/use-cases/signup-alerts)을 설정하면, 두 알림이 퍼널처럼 이어져서 보여요.

## 알림이 오지 않을 때

- **먼저 Stripe를 확인하세요.** Workbench에서 대상을 열고 **Event deliveries** 탭을 확인하세요. "Invalid JSON"과 함께 `400`이 보이면 Stripe JSON이 아닌 다른 데이터가 URL로 들어온 것이에요. `429`는 일일 한도에 도달했다는 뜻이에요.
- **다음으로 Pocket Alert 웹훅 기록을 확인하세요.** 요청은 있는데 메시지 일부가 비어 있다면, 해당 이벤트에 템플릿 경로가 존재하지 않는 것이에요. 기록에서 본문을 복사해 필드 이름을 확인하세요.
- **실수로 Thin 페이로드를 선택한 경우.** 푸시에 금액이 비어 있고 기록 본문에 `related_object` 대신 `data`가 있다면, 대상을 Thin으로 만든 것이에요. Snapshot으로 새로 만드세요.
- **2단계에서 서명 오류가 날 때.** 대상마다 고유한 `whsec_` 시크릿이 있고, 샌드박스 시크릿은 라이브 시크릿과 달라요. 또한 프록시나 프레임워크 미들웨어 같은 상위 계층이 본문을 다시 인코딩하지 않는지도 확인하세요.

## 자주 묻는 질문

### 이 방식이 Stripe 대시보드 앱을 대체하나요?

아니요, 대체할 필요도 없어요. Stripe 앱은 환불하거나 고객을 조회하거나 잔액을 확인하는 곳이에요. Pocket Alert는 알림 자체를 담당해요. 문구, 우선순위, 버튼을 직접 정하고, 서버, CI, 폼에서 오는 다른 알림과 같은 피드에서 받아볼 수 있어요.

### 어떤 이벤트가 푸시 알림으로 받을 만한가요?

위의 네 가지부터 시작하세요. SaaS 정기 결제라면 `invoice.paid`를 추가하면 좋고, `customer.subscription.deleted`로 해지를 파악할 수 있어요. Stripe도 실제로 사용하는 이벤트만 구독하라고 권장하는데, 그래야 휴대폰도 덜 시끄러워요.

### 판매 건마다 말고 하루에 한 번만 푸시 알림을 받을 수 있나요?

웹훅으로는 안 돼요. 판매 웹훅의 우선순위를 `silent`로 낮추면 소리 없이 피드에 쌓이고, `high`와 `critical`은 직접 대응이 필요한 이벤트에만 남겨 두세요.

### 무료인가요?

Stripe 웹훅은 무료예요. Pocket Alert 무료 플랜은 기기 한 대에서 하루 50건까지 보낼 수 있어요. 작은 스토어라면 충분해요. 방해 금지 모드를 무시하는 치명적 알림은 유료 [플랜](/pricing)에서 쓸 수 있어요.

[무료 계정 만들기](/signup)를 하고 URL 하나를 Stripe에 붙여 넣으세요. 다음 판매 알림이 바로 휴대폰에 도착할 거예요.
