返回博客

Stripe 付款推送通知:每笔销售、失败扣款与争议都推送到手机

Stripe 付款推送通知:每笔销售、失败扣款与争议都推送到手机

当天的第一笔销售,是你最想听到的消息。凌晨 2 点失败的续费扣款更重要,而争议则有截止日期:如果没有及时回应,你就会失去这笔款项。Stripe 在这三件事发生的那一刻就知道了,但你要等到下次打开控制台才会发现。

Stripe 自己确实提供通知功能。适用于 iOS 和 Android 的 Stripe 控制台应用可以推送新付款、新客户、有争议的付款、已到账的转账以及每日汇总,控制台也能就账户事件给你发邮件。这些已经覆盖了不少场景。但它不给你足够的控制权:你无法自定义文案,无法让失败的发票比销售提醒更醒目,也无法把你自己系统里的事件汇入同一个消息流。而从 Stripe 到 Pocket Alert 的 Webhook 可以做到这些。

准备工作

  • 一个有权创建 Webhook 的 Stripe 账户(管理员或开发者角色)。
  • 一个 Pocket Alert 账户、来自 API Keys 的 API 密钥,以及装在你的 iPhone 或 Android 手机上的应用。
  • 如果要走代码方案:Node 20 或更高版本,以及一个可以公网访问的运行环境。

第 1 级:无需代码

Stripe 会把每个事件作为 JSON 发送,而 Pocket Alert Webhook 可以接收 JSON 并通过模板渲染。这就是全部所需的底层连接。

1. 为每种事件类型创建一个 Pocket Alert Webhook

关键技巧是:每类事件对应一个 Webhook。推送标题始终是 Webhook <name>,所以名称决定了你在锁屏上看到的内容,而且每个 Webhook 都有自己的默认优先级和按钮。免费套餐包含一个 Webhook,因此先从销售开始;完整的四个需要付费套餐,付费套餐同时还解锁操作按钮。

你可以在控制台的 Webhooks 页面创建 Webhook,在那里设置名称、模板和默认优先级。操作按钮需要通过 API 设置,因此最快的方式是为每个 Webhook 调用一次 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 标识符。你的接收地址是 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/... 地址。

每个 Pocket Alert Webhook 都要这样做一次,使每个 Stripe 目标只对应一个事件类型和一个地址:

Stripe 事件Pocket Alert Webhook推送标题优先级
checkout.session.completedStripe saleWebhook Stripe sale默认
invoice.payment_failedStripe payment failedWebhook Stripe payment failed高
charge.dispute.createdStripe disputeWebhook Stripe dispute紧急
customer.subscription.createdStripe subscriptionWebhook Stripe subscription低

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 控制台中打开该 Webhook:它的历史记录会显示 Stripe 发送的每一次请求,包括请求头、原始请求体、渲染后的消息以及响应状态。如果某个字段显示为空,你可以在这里看到是哪个路径写错了。

一笔销售的推送大致如下:

Webhook Stripe sale
4900 usd from [email protected] (paid)
[Open in Stripe]

模板做不到的事

在依赖它之前,先明确它的限制:

  • 金额以最小货币单位表示。 Stripe 对 49.00 美元发送 4900,对 5000 日元发送 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,而不是邮箱。
  • 每个事件都计入每日配额。 免费套餐每天有 50 条消息。超过后,Pocket Alert 会返回 429,Stripe 会将其视为投递失败,并在正式模式下最多重试三天。

第 2 级:一个经过验证的小型处理程序

如果你想要真正的货币格式化、签名校验,以及用于所有事件的单个端点,可以在 Stripe 和 Pocket Alert 之间放一个约六十行的 Node 程序。它使用 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 请求体解析器会破坏签名。它还会拒绝超过五分钟的事件,从而防止重放攻击。
  • 处理程序会在调用 Pocket Alert 之前返回 200,因为 Stripe 需要快速得到 2xx 响应。STRIPE_SECRET_KEY 只需要一个具有读取权限的受限密钥即可,因为这段代码从不调用 Stripe API。
  • Intl.NumberFormat 知道每种货币有几位小数,因此 4900 usd 会变成 $49.00,5000 jpy 会变成 ¥5,000。
  • livemode 标志会选择正确的控制台路径,因此测试模式的事件会打开测试模式页面。

在 Stripe 中,创建一个使用 Snapshot 负载、包含全部四个事件并指向你服务器地址的事件目标,然后从目标页面复制它的 whsec_ 签名密钥。要在本地测试,可以运行 stripe listen --forward-to localhost:4242/stripe-webhook,它会打印一个可用的密钥;再运行 stripe trigger invoice.payment_failed,即可发送一个带签名的测试事件。

最终在手机上看到的效果是:一条标题为“Sale $49.00”的推送,下方显示“[email protected] · paid”;而争议推送会把你唤醒,并在正文中告诉你截止日期。

想把销售和注册合并到同一个消息流中吗?把注册表单也通过注册提醒发送到同一个应用,这两类消息读起来就像一条转化漏斗。

如果没有收到推送

  • 先检查 Stripe。 在 Workbench 中打开该目标,查看 Event deliveries 标签页。如果显示 400 且提示“Invalid JSON”,说明到达该地址的内容不是 Stripe 的 JSON。429 则表示你已达到每日上限。
  • 然后检查 Pocket Alert 的 Webhook 历史记录。 如果请求在那里但消息的部分内容为空,说明该事件中不存在模板里的某个路径。从历史记录中复制请求体,检查字段名称。
  • 误用了 Thin 负载。 如果推送中的金额为空,而历史记录的请求体中是 related_object 而不是 data,说明该目标是以 Thin 格式创建的。请使用 Snapshot 重新创建一个。
  • 第 2 级中的签名错误。 每个目标都有自己的 whsec_ 密钥,沙盒密钥与正式环境密钥不同。另外请确认上游没有代理或框架中间件重新编码了请求体。

常见问题

这能替代 Stripe 控制台应用吗?

不能,也没有必要。Stripe 应用适合用于退款、查询客户或查看余额。Pocket Alert 提供的是提醒本身:你自定义的文案、优先级和按钮,并与来自服务器、CI 和表单的其他提醒汇聚在同一个消息流中。

哪些事件值得推送?

先从上面的四个开始。对于 SaaS 续费,invoice.paid 是不错的补充;customer.subscription.deleted 则能告诉你客户流失的情况。Stripe 建议只订阅你实际会用到的事件,这样你的手机也能保持安静。

能每天只收到一条推送,而不是每笔销售一条吗?

Webhook 本身做不到。把销售 Webhook 的优先级降为 silent(静默),这样销售会被收集到消息流中但不会发出声音,同时把 high 和 critical 保留给真正需要你处理的事件。

这是免费的吗?

Stripe Webhook 本身不收费。Pocket Alert 的免费套餐在一台设备上每天提供 50 条消息,对于小型店铺已经足够。能够突破勿扰模式的紧急提醒则需要付费套餐。

创建免费账户,把一个地址粘贴到 Stripe 中,下一笔销售就会出现在你的手机上。

分享这篇文章