Avvisi di pagamento Stripe: farsi chiamare quando i soldi sono a rischio

Indice

Quali eventi Stripe hanno davvero bisogno di te
Passo 1 — Un canale per livello di urgenza
Passo 2 — Aggiungi gli endpoint in Stripe
Passo 3 — Rendi leggibile il payload
Passo 4 — Provalo senza aspettare un pagamento vero
Cosa questa configurazione non ti dà
Domande frequenti
Stripe può chiamarmi direttamente?
Un avviso di contestazione mi sveglierà davvero?
Il mio socio può ricevere gli stessi avvisi?
E la modalità test?
In chiusura
Contenuti correlati

Stripe ti manda email su tutto e su niente. Un addebito riuscito, un rinnovo di abbonamento fallito e un chargeback arrivano come lo stesso tipo di messaggio nella stessa casella, e quando li leggi hai già perso la differenza tra loro.

La soluzione non è più notifiche. È dare a ogni evento Stripe l'urgenza che merita davvero: una notifica discreta quando qualcuno paga, un avviso sensibile al tempo quando un rinnovo fallisce, e una telefonata quando arriva una contestazione con una scadenza per rispondere.

Quali eventi Stripe hanno davvero bisogno di te

Non tutti gli eventi meritano una notifica, e quelli che la meritano non sono ugualmente urgenti.

Evento Stripe	Perché conta	Urgenza
`payment_intent.succeeded`	Qualcuno ha pagato. Bello saperlo, mai urgente.	Normale
`invoice.payment_failed`	Un rinnovo è fallito. C'è una finestra di tentativi prima che l'abbonamento decada.	Sensibile al tempo
`charge.dispute.created`	Un chargeback. Stripe indica una scadenza di risposta fissata dal circuito, e mancarla fa perdere il caso d'ufficio.	Chiamata
`payment_intent.payment_failed`	Un pagamento una tantum è fallito. Utile in volume, rumoroso singolarmente.	Normale, o niente

La contestazione è l'unica che giustifica una telefonata. Il resto può aspettare che sia tu a prendere il telefono; una contestazione notata una settimana dopo è denaro che non avresti comunque trattenuto.

Passo 1 — Un canale per livello di urgenza

Crea tre canali in Echobell, perché l'urgenza è un'impostazione del canale:

Stripe · Ricavi — notifiche normali, per i pagamenti riusciti
Stripe · Pagamento fallito — sensibile al tempo
Stripe · Contestazione — chiamata

Copia l'URL webhook di ciascun canale dalle sue impostazioni. Punterai Stripe su tutti e tre.

Già che ci sei, attiva Solo POST su ognuno. Stripe invia sempre in POST, e così eviti che un'anteprima di link o il completamento automatico della barra degli indirizzi facciano scattare il canale per sbaglio.

Passo 2 — Aggiungi gli endpoint in Stripe

Nella dashboard di Stripe vai su Developers → Webhooks → Add endpoint, incolla l'URL del canale e seleziona solo gli eventi che quel canale deve gestire.

Aggiungi un endpoint per canale invece di uno per tutto. Stripe permette di scegliere gli eventi per endpoint, quindi l'instradamento avviene dalla sua parte e i tuoi canali restano semplici.

Se preferisci un solo endpoint, puntalo su un canale e filtra con una condizione:

type == "charge.dispute.created"

Le condizioni si scrivono senza le parentesi {{ }} usate dai template.

Passo 3 — Rendi leggibile il payload

Stripe invia un body JSON fatto così:

{
  "type": "charge.dispute.created",
  "data": {
    "object": {
      "amount": 4900,
      "currency": "usd",
      "reason": "fraudulent",
      "status": "warning_needs_response"
    }
  }
}

Quindi i template del canale pescano dentro data.object:

Titolo

Contestazione: {{data.object.reason}}

Corpo

{{data.object.amount}} {{data.object.currency}} contestati
Stato: {{data.object.status}}

Una trappola in cui cascano tutti: gli importi di Stripe sono nell'unità monetaria più piccola. 4900 sono 49,00 $, non 4.900 $. I template di Echobell sostituiscono il valore così com'è, quindi o dividi prima di inviare, o scrivi la valuta dopo e leggilo come centesimi. Se il numero deve essere giusto a colpo d'occhio, metti la divisione in ciò che sta tra Stripe ed Echobell: un Worker, un'automazione, un tuo endpoint.

Per il canale ricavi, stessa idea con meno parole:

Titolo

+{{data.object.amount}} {{data.object.currency}}

Corpo

{{data.object.description}}

Passo 4 — Provalo senza aspettare un pagamento vero

La CLI di Stripe può lanciare payload reali sul tuo endpoint:

stripe trigger payment_intent.succeeded
stripe trigger charge.dispute.created

Fallo prima di farci affidamento. È anche il modo più rapido di vedere cosa rende il template quando un campo che davi per scontato arriva null.

Cosa questa configurazione non ti dà

Due limiti da conoscere prima di metterla davanti ai tuoi ricavi.

Echobell non verifica la firma di Stripe. Stripe firma ogni webhook con un header Stripe-Signature, e verificarlo richiede il segreto dell'endpoint. L'endpoint webhook di Echobell non fa quel controllo, quindi l'URL del canale è l'unica cosa che lo protegge. Trattalo come un segreto, tieni Solo POST attivo e non incollarlo in un repository pubblico o in uno screenshot.

Puoi aggiungere un controllo debole con una condizione:

header["stripe-signature"] != ""

Conferma che qualcosa sta inviando una richiesta con la forma di Stripe. Non conferma che fosse Stripe. Se una notifica falsificata causasse un danno reale — e non solo un momento di confusione — metti davanti un tuo endpoint, verifica lì la firma e fai chiamare Echobell da lui.

Questo è un percorso di allerta, non un registro contabile. Stripe riprova le consegne di webhook fallite, ma le notifiche non sono una traccia di ciò che è successo. Riconcilia con Stripe, non con lo storico delle notifiche.

Domande frequenti

Stripe può chiamarmi direttamente?

No. Stripe manda email e webhook. Una telefonata significa instradare un webhook verso qualcosa che sappia farla partire.

Un avviso di contestazione mi sveglierà davvero?

Se il canale è in modalità chiamata, sì: arriva come chiamata in arrivo e squilla attraverso Full Immersion e Non disturbare. Vedi attraversare Full Immersion su iOS per gli avvisi critici.

Il mio socio può ricevere gli stessi avvisi?

Sì. Condividi il canale e ogni iscritto sceglie il proprio tipo di notifica. Tu puoi prenderti le chiamate mentre qualcun altro riceve una notifica discreta per lo stesso evento.

E la modalità test?

Gli eventi in modalità test di Stripe vanno agli endpoint registrati in modalità test. Registra l'URL del canale in entrambe se vuoi vedere quel traffico, oppure solo in test finché non ti fidi della configurazione.

In chiusura

Tre canali, tre endpoint, un template ciascuno. Il punto non è che vieni avvisato da Stripe: già lo eri. È che un chargeback smette di somigliare esattamente a una ricevuta.

Scarica Echobell per iPhone o prendilo su Google Play, poi lancia stripe trigger charge.dispute.created e lascia che il telefono squilli una volta apposta.