Voltar para o blog

Notificações push de pagamentos do Stripe: um alerta no celular para cada venda, cobrança recusada e disputa

Notificações push de pagamentos do Stripe: um alerta no celular para cada venda, cobrança recusada e disputa

A primeira venda do dia é a que você quer saber na hora. A renovação recusada às 2 da manhã importa mais, e uma disputa tem prazo: se você não responder a tempo, perde o valor. O Stripe sabe dos três no instante em que acontecem. Você só descobre quando abre o Dashboard de novo.

O Stripe tem notificações próprias. O app Stripe Dashboard para iOS e Android envia notificações push de novos pagamentos, novos clientes, pagamentos contestados, transferências depositadas e um resumo diário, e o Dashboard pode enviar e-mails sobre eventos da conta. Isso cobre bastante coisa. O que não oferece é controle: você não escolhe o texto, não consegue deixar uma fatura não paga mais alta que uma venda, e não consegue enviar nada dos seus próprios sistemas para o mesmo feed. Um webhook do Stripe para o Pocket Alert resolve isso.

O que você precisa

  • Uma conta no Stripe com permissão para criar webhooks (papel de Administrador ou Desenvolvedor).
  • Uma conta no Pocket Alert, uma chave de API em Chaves de API e o app no seu celular iPhone ou Android.
  • Para o caminho com código: Node 20 ou superior e um lugar público para executá-lo.

Nível 1: sem código

O Stripe envia cada evento como JSON, e os webhooks do Pocket Alert aceitam JSON e o renderizam por meio de um modelo. É só isso que essa configuração precisa.

1. Crie um webhook do Pocket Alert por tipo de evento

O truque é ter um webhook para cada tipo de evento. O título da notificação push é sempre Webhook <name>, então o nome define o que você vê na tela de bloqueio, e cada webhook tem sua própria prioridade padrão e seus próprios botões. O plano gratuito inclui um webhook, então comece com as vendas; o conjunto completo de quatro exige um plano pago, que também libera os botões.

Você pode criar webhooks no console em Webhooks, onde define o nome, o modelo e a prioridade padrão. Os botões de ação são configurados pela API, então a forma mais rápida de fazer tudo de uma vez é uma chamada de curl por webhook:

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

A resposta contém um slug url. Sua URL de recebimento é https://p4a.me/wh/<slug>, e o console também a mostra. actions é uma string JSON, não um array, por isso as aspas estão escapadas.

Repita com estes corpos para os outros três:

{
  "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%\"}]"
}

Os níveis vão de -2 (silencioso) a 2 (crítico). Um pagamento recusado é high (alta), que atravessa o Foco no iPhone. Uma disputa é critical (crítica), que toca mesmo com a chave de silêncio ativada e com o Não perturbe. Alertas críticos exigem um plano pago; no plano gratuito, chegam como high. Novas assinaturas são low (baixa): bom saber, mas não há motivo para vibrar.

O botão de cópia na notificação de pagamento recusado copia para a área de transferência a página de pagamento hospedada da fatura, pronta para colar em um e-mail do tipo "seu cartão foi recusado".

2. Adicione destinos de eventos no Stripe

No Stripe Dashboard, abra Workbench, vá para a aba Webhooks e clique em Create an event destination. Depois:

  1. Escolha Your account.
  2. Selecione o payload Snapshot. O Stripe agora recomenda o Thin para código novo, mas um evento thin traz apenas o ID do objeto, então um modelo não tem valor ou e-mail para mostrar. O Snapshot envia o objeto completo.
  3. Selecione o evento, por exemplo checkout.session.completed.
  4. Escolha Webhook endpoint como tipo de destino e cole a URL https://p4a.me/wh/... correspondente.

Faça isso uma vez para cada webhook do Pocket Alert, para que cada destino do Stripe leve um tipo de evento a uma URL:

Evento do StripeWebhook do Pocket AlertTítulo da notificaçãoNível
checkout.session.completedStripe saleWebhook Stripe salepadrão
invoice.payment_failedStripe payment failedWebhook Stripe payment failedalta
charge.dispute.createdStripe disputeWebhook Stripe disputecrítica
customer.subscription.createdStripe subscriptionWebhook Stripe subscriptionbaixa

O Stripe permite 16 destinos de eventos por conta, então quatro está tranquilo.

Checkout ou PaymentIntents? Se seus clientes pagam pelo Checkout ou por Payment Links, use checkout.session.completed. Se você cria seu próprio formulário de pagamento, use payment_intent.succeeded no lugar, altere o modelo para %data.object.amount% %data.object.currency% %data.object.receipt_email% e o botão para /payments/%data.object.id%. Assinar os dois eventos gera duas notificações por venda, porque um pagamento pelo Checkout dispara ambos.

3. Teste

Crie um pagamento de teste em um sandbox, ou execute stripe trigger checkout.session.completed com a CLI do Stripe. Depois, abra o webhook no console do Pocket Alert: o histórico mostra cada requisição enviada pelo Stripe, com cabeçalhos, corpo bruto, mensagem renderizada e código de resposta. Quando um campo sai vazio, é ali que você vê qual caminho estava errado.

Uma venda chega assim:

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

O que o modelo não consegue fazer

Deixe claros os limites antes de depender dele:

  • Os valores estão em unidades menores. O Stripe envia 4900 para US$ 49,00 e 5000 para ¥5.000, porque o iene não tem centavos. O modelo copia os valores como vêm e não consegue dividir por 100. Você se acostuma a ler 4900 usd rapidamente, mas se quiser $49.00, use o Nível 2.
  • Não há verificação de assinatura. O Stripe assina cada requisição com o cabeçalho Stripe-Signature. O Pocket Alert não verifica assinaturas de terceiros; o slug aleatório na URL é o único segredo. Quem descobrir a URL pode enviar "vendas" falsas. Para uma notificação, isso é um incômodo, não uma falha de segurança, já que nada é entregue de fato. Mantenha a URL privada mesmo assim, e use o Nível 2 se precisar de prova de que a notificação veio do Stripe.
  • Não há condições. Um modelo não consegue dizer "só notifique vendas acima de US$ 500" ou "ignore o modo de teste". A filtragem acontece no Stripe, pelos eventos que você escolhe, ou no código.
  • Os botões do Dashboard apontam para o modo ao vivo. Objetos de teste ficam em dashboard.stripe.com/test/..., então, em um evento do modo de teste, o botão abre uma página que não existe. Disputas da API Charges legada não têm payment_intent, o que deixa esse botão com um link vazio.
  • As assinaturas mostram apenas o primeiro preço. items.data.0 é o primeiro item da fatura. O evento traz um ID de cliente, não um e-mail.
  • Cada evento conta para a sua cota diária. O plano gratuito tem 50 mensagens por dia. Além disso, o Pocket Alert responde com 429, e o Stripe trata isso como falha de entrega e, no modo ao vivo, tenta de novo por até três dias.

Nível 2: um pequeno manipulador com verificação

Quando você quer formatação real de moeda, verificação de assinatura e um único endpoint para todos os eventos, coloque cerca de sessenta linhas de Node entre o Stripe e o Pocket Alert. Ele usa a biblioteca oficial do Stripe para verificar a assinatura e POST /v1/messages para enviar a notificação push.

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

Os detalhes que importam:

  • express.raw mantém o corpo como bytes. constructEvent precisa da requisição exatamente como o Stripe a enviou, e um parser de JSON no corpo quebra a assinatura. Ele também rejeita eventos com mais de cinco minutos, o que impede replays.
  • O manipulador responde 200 antes de chamar o Pocket Alert, porque o Stripe espera um 2xx rápido. Uma chave restrita com acesso de leitura basta para STRIPE_SECRET_KEY; este código nunca chama a API do Stripe.
  • Intl.NumberFormat conhece quantas casas decimais cada moeda tem, então 4900 usd vira $49.00 e 5000 jpy vira ¥5,000.
  • A flag livemode escolhe o caminho certo do Dashboard, então eventos do modo de teste abrem páginas do modo de teste.

No Stripe, crie um destino de evento com payload Snapshot, os quatro eventos e a URL do seu servidor, e depois copie o segredo de assinatura whsec_ na página do destino. Para testar localmente, stripe listen --forward-to localhost:4242/stripe-webhook exibe um segredo para usar, e stripe trigger invoice.payment_failed envia um evento de teste assinado.

O resultado no celular é uma notificação push com o título "Sale $49.00" e "[email protected] · paid" embaixo, e uma disputa que te acorda com o prazo no texto.

Quer ver a venda e o cadastro no mesmo feed? Envie seu formulário de cadastro para o mesmo app com alertas de cadastro e os dois se leem como um funil.

Se nada chegar

  • Verifique primeiro o Stripe. Abra o destino no Workbench e confira a aba Event deliveries. Um 400 com "Invalid JSON" significa que algo que não é JSON do Stripe chegou na URL. Um 429 significa que você atingiu o limite diário.
  • Depois, o histórico do webhook no Pocket Alert. Se a requisição aparece e a mensagem está em branco em alguns pontos, um caminho do modelo não existe naquele evento. Copie o corpo do histórico e confira os nomes dos campos.
  • Payload thin por engano. Se a notificação mostra valores vazios e o corpo no histórico tem related_object em vez de data, o destino foi criado como Thin. Crie um novo com Snapshot.
  • Erros de assinatura no Nível 2. Cada destino tem seu próprio segredo whsec_, e o segredo de sandbox é diferente do ao vivo. Confirme também que nada no caminho, como um proxy ou um middleware do framework, reencoda o corpo.

Perguntas frequentes

Isso substitui o app Stripe Dashboard?

Não, e não precisa. O app do Stripe é o lugar para fazer reembolsos, consultar um cliente ou ver o saldo. O Pocket Alert entrega o alerta em si: seu texto, seus níveis de prioridade e seus botões, em um feed compartilhado com o resto dos seus alertas de servidores, CI e formulários.

Quais eventos valem uma notificação?

Comece pelos quatro acima. invoice.paid é um bom extra para renovações de SaaS, e customer.subscription.deleted avisa sobre cancelamentos. O Stripe recomenda assinar apenas os eventos que você usa, e isso também deixa seu celular mais silencioso.

Dá para receber uma notificação por dia em vez de uma por venda?

Não pelo webhook. Reduza o nível do webhook de vendas para silent (silenciosa), assim as vendas se acumulam no feed sem som, e reserve high e critical para os eventos que exigem sua atenção.

É gratuito?

Os webhooks do Stripe não custam nada. O plano gratuito do Pocket Alert cobre 50 mensagens por dia em um dispositivo, o que é suficiente para uma loja pequena. Alertas críticos que ignoram o Não perturbe estão nos planos pagos.

Crie uma conta gratuita, cole uma URL no Stripe, e a próxima venda chega no seu celular.

Compartilhe este artigo