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

> Aponte um webhook do Stripe para o Pocket Alert e receba uma notificação push para cada pagamento, fatura não paga, disputa e nova assinatura. Sem código para o básico, cerca de sessenta linhas de Node para valores formatados e assinaturas verificadas.

*20.10.2026*

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

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](/use-cases/payment-alerts) 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](/account/apikeys) e o app no seu celular [iPhone ou Android](/get-app).
- 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](/tools/webhook) 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](/pricing) pago, que também libera os botões.

Você pode criar webhooks no console em [Webhooks](/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:

```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
```

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:

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

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:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Evento do Stripe</th><th>Webhook do Pocket Alert</th><th>Título da notificação</th><th>Nível</th></tr></thead>
<tbody>
<tr><th><code>checkout.session.completed</code></th><td>Stripe sale</td><td>Webhook Stripe sale</td><td>padrão</td></tr>
<tr><th><code>invoice.payment_failed</code></th><td>Stripe payment failed</td><td>Webhook Stripe payment failed</td><td>alta</td></tr>
<tr><th><code>charge.dispute.created</code></th><td>Stripe dispute</td><td>Webhook Stripe dispute</td><td>crítica</td></tr>
<tr><th><code>customer.subscription.created</code></th><td>Stripe subscription</td><td>Webhook Stripe subscription</td><td>baixa</td></tr>
</tbody>
</table>
</div>

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:

```text
Webhook Stripe sale
4900 usd from alex@example.com (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.

```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
```

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 "alex@example.com · 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](/use-cases/signup-alerts) 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](/pricing) pagos.

[Crie uma conta gratuita](/signup), cole uma URL no Stripe, e a próxima venda chega no seu celular.
