# Stripe の支払い通知：売上・決済失敗・異議申し立てをスマホにプッシュ通知

> Stripe の Webhook を Pocket Alert に向けると、支払い、請求の失敗、異議申し立て、新しいサブスクリプションごとにプッシュ通知が届きます。基本設定はコード不要で、金額の整形や署名の検証は約 60 行の Node で行えます。

*20.10.2026*

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

一日最初の売上は、ぜひ知っておきたい情報です。午前 2 時の更新失敗はそれ以上に重要ですし、異議申し立てには期限があり、期限内に対応しなければ入金を失います。Stripe はこの 3 つが起きた瞬間に把握しています。ただ、あなたがそれを知るのは次にダッシュボードを開いたときです。

Stripe には独自の通知機能もあります。iOS と Android の Stripe Dashboard アプリは、新しい支払い、新規顧客、異議申し立てのあった支払い、入金された送金、日次サマリーをプッシュ通知で知らせてくれますし、ダッシュボードからアカウントのイベントをメールで受け取ることもできます。これで多くの場面はカバーできます。ただし、通知内容を自分で決めることはできず、失敗した請求を売上より目立たせることもできません。自社システムからの通知を同じフィードにまとめることもできません。Stripe から [Pocket Alert](/use-cases/payment-alerts) への Webhook を設定すると、これらが可能になります。

## 必要なもの

- Webhook を作成できる権限（Administrator または Developer ロール）を持つ Stripe アカウント。
- Pocket Alert のアカウント、[API キー](/account/apikeys)、そして [iPhone または Android](/get-app) のスマホにインストールしたアプリ。
- コードで設定する場合は、Node 20 以降と、公開アクセスできる実行環境。

## レベル 1：コード不要

Stripe はすべてのイベントを JSON で送信し、[Pocket Alert の Webhook](/tools/webhook) は JSON を受け取ってテンプレートで描画します。必要な仕組みはこれだけです。

### 1. イベントの種類ごとに Pocket Alert の Webhook を作成する

イベントの種類ごとに Webhook を 1 つずつ作るのがポイントです。プッシュ通知のタイトルは常に `Webhook <name>` になるので、名前によってロック画面で何が表示されるかが決まります。また、Webhook ごとにデフォルトの優先度とボタンを設定できます。無料プランでは Webhook は 1 つまでなので、まずは売上用から始めてください。4 つすべてを作るには有料の[プラン](/pricing)が必要で、アクションボタンも有料プランで使えるようになります。

コンソールの [Webhooks](/webhooks) で Webhook を作成すると、名前、テンプレート、デフォルトの優先度を設定できます。アクションボタンは API で設定するため、すべてをまとめて設定するなら Webhook ごとに curl を 1 回ずつ実行するのが最も手早い方法です。

```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 文字列なので、引用符をエスケープしています。

残りの 3 つも、次のボディを使って同じように作成します。

```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` に設定します。知っておくと良い情報ですが、スマホを震わせるほどではありません。

支払い失敗のプッシュ通知にあるコピーボタンを押すと、請求書の支払いページの URL がクリップボードにコピーされます。「お支払いのカードが承認されませんでした」というメールに貼り付けるのに便利です。

### 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 の Webhook 1 つにつき 1 回これを行い、Stripe の送信先ごとに 1 種類のイベントを 1 つの URL に送るようにします。

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Stripe のイベント</th><th>Pocket Alert の Webhook</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 件までイベントの送信先を作成できるので、4 件なら問題ありません。

**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%` に変更します。両方を購読すると売上ごとに 2 件の通知が届きます。Checkout の支払いでは両方のイベントが発生するためです。

### 3. テストする

サンドボックスでテスト決済を作成するか、Stripe CLI で `stripe trigger checkout.session.completed` を実行します。その後、Pocket Alert のコンソールで該当の Webhook を開いてください。履歴には 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 は非公開にしてください。プッシュ通知が Stripe から送られたものだと証明する必要がある場合は、レベル 2 を使ってください。
- **条件を指定できません。** 「500 ドル以上の売上だけ通知する」や「テストモードは除外する」といった条件はテンプレートでは指定できません。フィルタリングは、選んだイベントで Stripe 側で行うか、コードで行ってください。
- **ダッシュボードのボタンは本番モードを指します。** テスト用のオブジェクトは `dashboard.stripe.com/test/...` の下にあるため、テストモードのイベントでボタンを押すと、存在しないページが開きます。従来の Charges API による異議申し立てには `payment_intent` がないため、そのボタンのリンクは空になります。
- **サブスクリプションは最初の価格だけを表示します。** `items.data.0` は最初の明細行です。イベントに含まれるのはメールアドレスではなく顧客 ID です。
- **すべてのイベントが 1 日の上限に加算されます。** 無料プランでは 1 日 50 件までのメッセージを送信できます。それを超えると Pocket Alert は `429` を返し、Stripe はこれを配信失敗として扱います。本番モードでは最大 3 日間リトライされます。

## レベル 2：検証付きの小さなハンドラー

実際の通貨表示、署名の検証、すべてのイベントに対応するエンドポイントが必要な場合は、Stripe と Pocket Alert の間に約 60 行の Node を置きます。署名の検証には 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 分より古いイベントは拒否されるため、リプレイ攻撃を防げます。
- Stripe は素早い `200` の応答を求めるため、ハンドラーは Pocket Alert を呼び出す前に `2xx` を返します。`STRIPE_SECRET_KEY` には読み取り権限を持つ制限付きキーで十分です。このコードは Stripe API を呼び出しません。
- `Intl.NumberFormat` は通貨ごとの小数点以下の桁数を把握しているため、`4900 usd` は `$49.00` に、`5000 jpy` は `¥5,000` になります。
- `livemode` フラグで正しいダッシュボードのパスを選ぶため、テストモードのイベントはテストモードのページを開きます。

Stripe では、**Snapshot** ペイロード、4 つのイベントすべて、サーバーの URL を指定して送信先を 1 つ作成してください。その後、送信先のページから `whsec_` の署名シークレットをコピーします。ローカルでテストするには、`stripe listen --forward-to localhost:4242/stripe-webhook` を実行するとシークレットが表示され、`stripe trigger invoice.payment_failed` で署名付きのテストイベントを送信できます。

スマホには「Sale $49.00」というタイトルのプッシュ通知が届き、その下に「alex@example.com · paid」と表示されます。異議申し立ての通知は、期限を本文に書いてあなたを起こしてくれます。

売上と新規登録を 1 つのフィードで確認したいですか。フォームの登録通知を同じアプリに送るには [新規登録の通知](/use-cases/signup-alerts) を使ってください。2 つを並べて見ると、ファネルのように読めます。

## 通知が届かない場合

- **まず Stripe を確認してください。** Workbench で送信先を開き、**Event deliveries** タブを見てください。「Invalid JSON」を伴う `400` は、Stripe の JSON ではない何かが URL に届いたことを示します。`429` は 1 日の上限に達したことを示します。
- **次に Pocket Alert の Webhook の履歴を確認してください。** リクエストは記録されているのにメッセージの一部が空になっている場合は、そのイベントに存在しないテンプレートのパスを指定している可能性があります。履歴からボディをコピーし、フィールド名を確認してください。
- **誤って Thin ペイロードを選んだ場合。** プッシュ通知で金額が空になり、履歴のボディに `related_object` ではなく `data` が含まれている場合は、送信先が Thin で作成されています。Snapshot で新しい送信先を作成し直してください。
- **レベル 2 で署名エラーが出る場合。** 送信先ごとに `whsec_` のシークレットがあり、サンドボックスのシークレットは本番のものと異なります。また、プロキシやフレームワークのミドルウェアなど、上流でボディが再エンコードされていないか確認してください。

## FAQ

### Stripe ダッシュボードアプリの代わりになりますか。

いいえ、代わりにする必要もありません。返金、顧客の検索、残高の確認は Stripe アプリで行うのが適しています。Pocket Alert が提供するのは通知そのものです。通知内容、優先度、ボタンを自分で決め、サーバー、CI、フォームからのアラートと同じフィードで受け取れます。

### どのイベントをプッシュ通知の対象にすべきですか。

まずは上の 4 つから始めてください。SaaS の更新を追跡するなら `invoice.paid` も便利です。`customer.subscription.deleted` は解約を知らせてくれます。Stripe は、実際に使うイベントだけを購読することを勧めています。そうすればスマホも静かに保てます。

### 売上ごとではなく、1 日 1 回の通知にできますか。

Webhook からはできません。売上用 Webhook の優先度を `silent` に下げると、音を鳴らさずにフィードへ蓄積できます。`high` と `critical` は、対応が必要なイベントのために残しておいてください。

### 無料で使えますか。

Stripe の Webhook は無料です。Pocket Alert の無料プランでは、1 台のデバイスで 1 日 50 件のメッセージを送信できます。小規模なストアなら十分です。おやすみモードを無視する緊急通知は、有料の[プラン](/pricing)で利用できます。

[無料アカウントを作成](/signup)して、Stripe に URL を 1 つ貼り付けてください。次の売上がスマホに届きます。
