Torna al blog

Notifiche push per pagamenti Stripe: un avviso sul telefono per ogni vendita, pagamento fallito e contestazione

Notifiche push per pagamenti Stripe: un avviso sul telefono per ogni vendita, pagamento fallito e contestazione

La prima vendita della giornata è quella di cui vuoi sapere subito. Il rinnovo fallito alle 2 di notte conta di più, e una contestazione ha una scadenza: se non rispondi in tempo, la perdi. Stripe sa di tutti e tre nel momento in cui succedono. Tu lo scopri quando riapri la Dashboard.

Stripe ha delle notifiche sue. L'app Stripe Dashboard per iOS e Android può inviarti notifiche push per nuovi pagamenti, nuovi clienti, pagamenti contestati, bonifici accreditati e un riepilogo giornaliero, e la Dashboard può inviarti email sugli eventi dell'account. Copre molto. Quello che non ti dà è il controllo: non puoi scegliere il testo, non puoi far suonare più forte una fattura non riscossa di una vendita, e non puoi far confluire nello stesso flusso eventi dei tuoi sistemi. Un webhook da Stripe a Pocket Alert lo permette.

Cosa ti serve

  • Un account Stripe con il permesso di creare webhook (ruolo Amministratore o Sviluppatore).
  • Un account Pocket Alert, una chiave API da Chiavi API e l'app sul tuo telefono iPhone o Android.
  • Per la parte con codice: Node 20 o successivo e un posto pubblico dove eseguirlo.

Livello 1: senza codice

Stripe invia ogni evento come JSON, e i webhook di Pocket Alert accettano JSON e lo visualizzano tramite un template. Non serve altro.

1. Crea un webhook Pocket Alert per tipo di evento

Il trucco è avere un webhook per ogni tipo di evento. Il titolo della notifica push è sempre Webhook <name>, quindi il nome decide cosa vedi sulla schermata di blocco, e ogni webhook ha la sua priorità predefinita e i suoi pulsanti. Il piano gratuito include un webhook, quindi inizia dalle vendite; il set completo di quattro richiede un piano a pagamento, che sblocca anche i pulsanti.

Puoi creare i webhook nella console su Webhook, dove imposti nome, template e priorità predefinita. I pulsanti di azione si impostano tramite API, quindi il modo più rapido per configurare tutto è una chiamata curl per 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

La risposta contiene uno url slug. Il tuo URL di ricezione è https://p4a.me/wh/<slug>, e la console lo mostra comunque. actions è una stringa JSON, non un array, ed è per questo che le virgolette sono escapate.

Ripeti con questi corpi per gli altri tre:

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

I livelli vanno da -2 (silenzioso) a 2 (critico). Un pagamento fallito è high, che passa la Full immersion su iPhone. Una contestazione è critical, che suona anche con l'interruttore silenzioso e Non disturbare attivi. Gli avvisi critici richiedono un piano a pagamento; nel piano gratuito arrivano come high. I nuovi abbonamenti sono low: utile saperlo, ma non c'è motivo di far vibrare il telefono.

Il pulsante di copia sulla notifica del pagamento fallito copia negli appunti la pagina di pagamento ospitata della fattura, pronta da incollare in un'email del tipo "la tua carta è stata rifiutata".

2. Aggiungi le destinazioni di eventi in Stripe

Nella Dashboard di Stripe apri Workbench, vai alla scheda Webhook e clicca su Create an event destination. Poi:

  1. Scegli Your account.
  2. Seleziona il payload Snapshot. Stripe oggi consiglia Thin per il nuovo codice, ma un evento thin contiene solo l'ID dell'oggetto, quindi un template non avrebbe importo né email da mostrare. Snapshot invia l'oggetto completo.
  3. Seleziona l'evento, per esempio checkout.session.completed.
  4. Scegli Webhook endpoint come tipo di destinazione e incolla l'URL https://p4a.me/wh/... corrispondente.

Fai così una volta per ogni webhook Pocket Alert, in modo che ogni destinazione Stripe porti un tipo di evento a un solo URL:

Evento StripeWebhook Pocket AlertTitolo pushLivello
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 consente 16 destinazioni di eventi per account, quindi quattro vanno benissimo.

Checkout o PaymentIntents? Se i clienti pagano tramite Checkout o Payment Links, usa checkout.session.completed. Se costruisci un tuo modulo di pagamento, usa invece payment_intent.succeeded e cambia il template in %data.object.amount% %data.object.currency% %data.object.receipt_email% e il pulsante in /payments/%data.object.id%. Sottoscrivere entrambi ti dà due notifiche per vendita, perché un pagamento Checkout genera entrambi gli eventi.

3. Provalo

Crea un pagamento di prova in un sandbox, oppure esegui stripe trigger checkout.session.completed con la CLI di Stripe. Poi apri il webhook nella console di Pocket Alert: la cronologia mostra ogni richiesta inviata da Stripe, con header, corpo grezzo, messaggio renderizzato e codice di risposta. Quando un campo esce vuoto, è lì che vedi quale percorso era sbagliato.

Una vendita arriva così:

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

Cosa non può fare il template

Sii chiaro sui limiti prima di affidarti al template:

  • Gli importi sono in unità minime. Stripe invia 4900 per 49,00 $ e 5000 per ¥5.000, perché lo yen non ha centesimi. Il template copia i valori così come sono e non può dividerli per 100. Ti abitui presto a leggere 4900 usd, ma se vuoi $49.00, usa il Livello 2.
  • Nessun controllo della firma. Stripe firma ogni richiesta con l'header Stripe-Signature. Pocket Alert non verifica le firme di terze parti; lo slug casuale nell'URL è l'unico segreto. Chi lo scopre può inviarti "vendite" false. Per una notifica è un fastidio, non una violazione, perché nulla viene evaso. Tieni comunque l'URL riservato, e usa il Livello 2 se ti serve la prova che una push proviene da Stripe.
  • Nessuna condizione. Un template non può dire "invia solo vendite sopra 500 $" o "ignora la modalità test". Il filtro avviene in Stripe tramite gli eventi che scegli, oppure nel codice.
  • I pulsanti della Dashboard puntano alla modalità live. Gli oggetti di test vivono sotto dashboard.stripe.com/test/..., quindi per un evento in modalità test il pulsante apre una pagina che non esiste. Le contestazioni dell'API Charges legacy non hanno payment_intent, e quel pulsante resta con un link vuoto.
  • Gli abbonamenti mostrano solo il primo prezzo. items.data.0 è la prima voce. L'evento contiene un ID cliente, non un'email.
  • Ogni evento conta nella quota giornaliera. Il piano gratuito prevede 50 messaggi al giorno. Oltre, Pocket Alert risponde 429, e Stripe lo considera una consegna fallita e, in modalità live, riprova per fino a tre giorni.

Livello 2: un piccolo gestore verificato

Quando vuoi una formattazione reale delle valute, il controllo delle firme e un solo endpoint per tutti gli eventi, inserisci circa sessanta righe di Node tra Stripe e Pocket Alert. Usa la libreria ufficiale di Stripe per verificare la firma e POST /v1/messages per inviare la notifica 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

I dettagli importanti:

  • express.raw mantiene il corpo come byte. constructEvent ha bisogno della richiesta esattamente come l'ha inviata Stripe, e un parser JSON del corpo rompe la firma. Inoltre rifiuta gli eventi più vecchi di cinque minuti, il che blocca i replay.
  • Il gestore risponde 200 prima di chiamare Pocket Alert, perché Stripe vuole una risposta 2xx rapida. Per STRIPE_SECRET_KEY basta una chiave con accesso in lettura: questo codice non chiama mai l'API di Stripe.
  • Intl.NumberFormat conosce il numero di decimali di ogni valuta, quindi 4900 usd diventa $49.00 e 5000 jpy diventa ¥5,000.
  • Il flag livemode sceglie il percorso corretto della Dashboard, così gli eventi in modalità test aprono pagine di test.

In Stripe crea una destinazione di eventi con payload Snapshot, tutti e quattro gli eventi e l'URL del tuo server, poi copia il segreto di firma whsec_ dalla pagina della destinazione. Per provare in locale, stripe listen --forward-to localhost:4242/stripe-webhook stampa un segreto da usare, e stripe trigger invoice.payment_failed invia un evento di prova firmato.

Il risultato sul telefono è una notifica push intitolata "Sale $49.00" con "[email protected] · paid" sotto, e una contestazione che ti sveglia con la scadenza nel testo.

Vuoi vedere vendite e iscrizioni nello stesso flusso? Invia il tuo modulo di registrazione alla stessa app con avvisi di iscrizione e le due cose si leggono come un funnel.

Se non arriva nulla

  • Controlla prima Stripe. Apri la destinazione in Workbench e guarda la scheda Event deliveries. Un 400 con "Invalid JSON" significa che all'URL è arrivato qualcosa che non è JSON di Stripe. Un 429 significa che hai raggiunto il limite giornaliero.
  • Poi la cronologia del webhook Pocket Alert. Se la richiesta è lì ma il messaggio è vuoto in alcuni punti, un percorso del template non esiste in quell'evento. Copia il corpo dalla cronologia e controlla i nomi dei campi.
  • Payload thin per errore. Se la notifica mostra importi vuoti e il corpo nella cronologia contiene related_object invece di data, la destinazione è stata creata come Thin. Creane una nuova con Snapshot.
  • Errori di firma nel Livello 2. Ogni destinazione ha il proprio segreto whsec_, e il segreto del sandbox è diverso da quello live. Assicurati anche che nulla a monte, come un proxy o un middleware del framework, ricodifichi il corpo.

Domande frequenti

Questo sostituisce l'app Stripe Dashboard?

No, e non deve farlo. L'app Stripe serve per fare rimborsi, cercare un cliente o controllare il saldo. Pocket Alert ti dà l'avviso vero e proprio: il tuo testo, i tuoi livelli di priorità e i tuoi pulsanti, in un flusso condiviso con il resto dei tuoi avvisi da server, CI e moduli.

Quali eventi meritano una notifica push?

Inizia dai quattro sopra. invoice.paid è un buon extra per i rinnovi SaaS, e customer.subscription.deleted ti segnala le disdette. Stripe consiglia di sottoscrivere solo gli eventi che usi, e così anche il telefono resta tranquillo.

Posso ricevere una notifica al giorno invece che una per vendita?

Non dal webhook. Abbassa il livello del webhook delle vendite a silent, così le vendite si accumulano nel flusso senza suono, e riserva high e critical agli eventi che richiedono la tua attenzione.

È gratuito?

I webhook di Stripe non costano nulla. Il piano gratuito di Pocket Alert copre 50 messaggi al giorno su un dispositivo, più che sufficienti per un piccolo negozio. Gli avvisi critici che superano Non disturbare sono disponibili nei piani a pagamento.

Crea un account gratuito, incolla un solo URL in Stripe, e la prossima vendita arriva sul tuo telefono.

Condividi questo articolo