블로그로 돌아가기

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

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

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

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

준비물

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

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

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

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

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

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

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 문자열이라서 따옴표를 이스케이프했어요.

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

{
  "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%\"}]"
}
{
  "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%\"}]"
}
{
  "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 하나로 보내도록 구성해요.

Stripe 이벤트Pocket Alert 웹훅푸시 제목우선순위
checkout.session.completedStripe saleWebhook Stripe saledefault
invoice.payment_failedStripe payment failedWebhook Stripe payment failedhigh
charge.dispute.createdStripe disputeWebhook Stripe disputecritical
customer.subscription.createdStripe subscriptionWebhook Stripe subscriptionlow

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가 보낸 모든 요청이 헤더, 원본 본문, 렌더링된 메시지, 응답 상태와 함께 표시돼요. 값이 비어 나오는 필드가 있다면 어느 경로가 잘못됐는지 여기서 바로 확인할 수 있어요.

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

Webhook Stripe sale
4900 usd from [email protected] (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를 써요.

npm install express stripe
// 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);
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" 제목에 "[email protected] · paid"가 아래에 표시된 푸시가 도착해요. 분쟁 알림은 본문에 기한이 적혀 있어서 바로 확인하게 해 줘요.

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

알림이 오지 않을 때

  • 먼저 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건까지 보낼 수 있어요. 작은 스토어라면 충분해요. 방해 금지 모드를 무시하는 치명적 알림은 유료 플랜에서 쓸 수 있어요.

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

이 글 공유하기