Come configurare il tuo sito per accettare webhook da Stripe

I webhook consentono a Stripe di inviare messaggi al tuo sito WordPress. La configurazione dei webhook è obbligatoria per alcune funzionalità di WP Simple Pay come l'invio di email, la creazione di piani di rateizzazione, consentire ai clienti di aggiornare i dettagli di pagamento della loro sottoscrizione e l'utilizzo della sua integrazione con AffiliateWP.

WP Simple Pay tenta di creare endpoint webhook automaticamente. Nella maggior parte dei casi, la configurazione manuale, come mostrato di seguito, non sarà necessaria.

Aggiungi un endpoint in Stripe

Per aggiungere gli endpoint webhook appropriati, nella tua Dashboard Stripe, vai su Sviluppatori → Webhook.

Fai clic su Aggiungi endpoint, quindi aggiungi l'URL trovato in WP Simple Pay → Impostazioni → Stripe → Webhook.

Non abilitare Ascolta eventi su account connessi poiché ciò interromperà la funzionalità dei webhook di WP Simple Pay.

Ora dovrai aggiungere gli eventi specifici da ascoltare facendo clic sul pulsante etichettato +Seleziona eventi. Dopo averlo fatto, puoi copiare e incollare ciascun evento elencato di seguito nella casella di ricerca Seleziona eventi da inviare → Cerca eventi.

Dopo aver cercato ogni termine, fai clic sulla casella di controllo per aggiungerlo e cerca termini aggiuntivi. Non fare clic su Aggiungi eventi finché non hai selezionato tutti gli eventi elencati di seguito:

• payment_intent.processing
• payment_intent.succeeded
• charge.failed
• charge.refunded
• charge.succeeded
• checkout.session.completed
• customer.subscription.deleted
• customer.subscription.updated
• invoice.payment_succeeded
• invoice.upcoming

I dettagli sulla funzionalità di ciascuno di questi eventi sono mostrati in fondo a questo documento.

Al termine dell'aggiunta degli eventi, fai clic su Aggiungi endpoint per completare il processo. Dopo aver aggiunto l'endpoint, dovresti vedere il nuovo URL elencato nelle impostazioni dei webhook.

Configurazione del segreto di firma del webhook

Stripe può firmare gli eventi webhook che invia ai tuoi endpoint per una maggiore sicurezza, e raccomandiamo vivamente di impostare questa opzione.

Per farlo, recupera il segreto del tuo endpoint dalle impostazioni dei webhook del tuo Dashboard. Seleziona l'endpoint aggiunto per il quale desideri ottenere il segreto, quindi fai clic sul pulsante Mostra .

Quindi copia il segreto di firma dalla Stripe Dashboard, torna su WP Simple Pay → Impostazioni → Stripe → Webhook nella tua bacheca WordPress, quindi incollalo nella casella di testo Segreto endpoint per la modalità di pagamento corrente.

Ripeti in modalità di test

Un endpoint webhook deve essere creato anche in Modalità di test. Attiva l'interruttore Modalità di test in alto a destra della dashboard di Stripe e ripeti i passaggi precedenti.

Descrizioni dei tipi di evento

invoice.payment_succeeded

• Utilizzato per incrementare i piani di rateizzazione e inviare le email “Conferma pagamento” e “Notifica pagamento” email per gli Abbonamenti.
• Espone l'azione simpay_webhook_subscription_created per ulteriori elaborazioni dopo la creazione di un abbonamento andata a buon fine.
• Espone l'azione simpay_webhook_invoice_payment_succeeded per ulteriori elaborazioni dopo l'elaborazione di una fattura.

<?php
add_action(
	'simpay_webhook_subscription_created',
	/**
	 * Fires when a subscription is created in Stripe.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event        $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\Subscription $subscription Stripe Subscription.
	 */
	function( $event, $subscription ) {
		// Do something.
	},
	10,
	2
);

<?php
add_action(
	'simpay_webhook_invoice_payment_succeeded',
	/**
	 * Fires when a subscription invoice payment has succeeded.
	 * Does not fire for the subscription creation (first) invoice.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event        $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\Invoice      $invoice Stripe Invoice object.
	 * @param \SimplePay\Vendor\Stripe\Subscription $subscription Stripe Subscription object.
	 */
	function( $event, $invoice, $subscription ) {
		// Do something.
	},
	10,
	3
);

Scopri come aggiungere codice personalizzato →

payment_intent.succeeded

• Invia le email “Conferma pagamento” e “Notifica pagamento” email per i pagamenti una tantum.
• Espone l'azione simpay_webhook_payment_intent_succeeded per ulteriori elaborazioni dopo un pagamento andato a buon fine

<?php
add_action(
	'simpay_webhook_payment_intent_succeeded',
	/**
	 * Fires when a one-time payment has succeeded.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event         $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\PaymentIntent $paymentintent Stripe PaymentIntent.
	 */
	function( $event, $paymentintent ) {
		// Do something.
	},
	10,
	2
);

Scopri come aggiungere codice personalizzato →

invoice.upcoming

• Invia il promemoria via email “Fattura in arrivo” email per l'aggiornamento di un Metodo di pagamento. Scopri di più

checkout.session.completed

• Utilizzato per rimuovere i record generati di Stripe Checkout abbandonati.
• Espone l'azione simpay_webhook_checkout_session_completed per ulteriori elaborazioni, se necessario.

charge.succeeded

• Invia le email “Conferma pagamento” e “Notifica pagamento” email per i pagamenti una tantum tramite addebito diretto ACH.
• Espone l'azione simpay_webhook_charge_succeeded per ulteriori elaborazioni dopo un pagamento andato a buon fine

charge.failed

• Espone l'azione simpay_webhook_charge_failed per ulteriori elaborazioni dopo il fallimento di un addebito.

Domande frequenti

I webhook sono obbligatori?

I webhook non sono necessari per elaborare i pagamenti e quando un webhook fallisce, ciò non indica che un pagamento non è stato elaborato. Tuttavia, i webhook vengono utilizzati per alimentare funzionalità come il rilevamento delle frodi, le ricevute via email, le notifiche delle fatture imminenti e la gestione dei piani di rateizzazione.

I webhook sono necessari per utilizzare la verifica via email quando viene rilevata una frode.

Anche se non stai utilizzando queste funzionalità al momento, è altamente raccomandato assicurarsi di aver configurato correttamente l'endpoint webhook per evitare confusione se decidi di abilitare queste funzionalità in futuro, o se WP Simple Pay richiede queste funzionalità per funzionalità future.

Perché vedo "WP Simple Pay potrebbe non funzionare correttamente."

WP Simple Pay tenta di avvisarti di una possibile errata configurazione o errore dell'endpoint webhook per evitare interruzioni delle funzionalità che utilizzano la funzionalità webhook (email, piani di rateizzazione, ecc.). Se WP Simple Pay non è in grado di verificare un evento webhook previsto, vedrai una bolla di notifica all'interno delle impostazioni del plugin e il messaggio di errore "WP Simple Pay potrebbe non funzionare correttamente."

Come risolvo un endpoint webhook mal configurato?

Per risolvere una possibile errata configurazione dell'endpoint webhook, visita Sviluppatori → Webhook nella tua dashboard Stripe (se sei in Modalità Test, visualizza i tuoi endpoint in modalità test).

Sotto Endpoint ospitati dovresti vedere una voce contenente il ricevitore webhook di WP Simple Pay: wp-json/wpsp/v1/webhook-receiver. Se non vedi questo endpoint, completa i passaggi di configurazione descritti all'inizio di questo articolo.

Fai clic sull'URL dell'endpoint WP Simple Pay per visualizzare la configurazione dell'endpoint. Qui troverai un elenco di eventi webhook che sono stati inviati all'endpoint.

Fai clic sulla scheda Falliti per elencare gli eventi che sono falliti.

Se hai eventi webhook falliti, selezionando una delle voci verranno visualizzate la risposta ricevuta dall'URL dell'endpoint. Questa risposta contiene spesso informazioni sul motivo per cui l'endpoint non è riuscito a elaborare l'evento nella sezione Risposta.

Impossibile connettersi all'host remoto

Stripe non è stato in grado di comunicare con il tuo server. Assicurati che il tuo web server risponda alle richieste e, in particolare, sia in grado di rispondere a tutti i nomi di dominio completi e indirizzi IP di Stripe.

Nessuna firma trovata corrispondente alla firma prevista per il payload

Stripe non è stato in grado di verificare i dati dell'evento webhook utilizzando i segreti di firma forniti in WP Simple Pay → Impostazioni → Stripe → Webhook. Mentre visualizzi il tuo endpoint webhook, fai clic su Mostra sotto Segreto di firma e aggiorna le impostazioni del tuo segreto di firma in WP Simple Pay per ogni modalità di pagamento.

404 ERR <!DOCTYPE html>

L'URL dell'endpoint webhook non è corretto e punta a una pagina 404 non trovata. Visita WP Simple Pay → Impostazioni → Stripe → Webhook per trovare il valore corretto del tuo URL dell'endpoint webhook e aggiorna l'endpoint in Stripe.

Ho verificato le impostazioni del mio endpoint, perché vedo ancora un errore?

WP Simple Pay è volutamente eccessivamente reattivo a possibili errori di configurazione per garantire che un vero errore non passi inosservato. Tuttavia, è ancora possibile ricevere notifiche di falso positivo di un evento webhook non configurato correttamente. Ciò può verificarsi se c'è un ritardo più lungo della media nell'invio dei dati dell'evento da parte di Stripe, o in alcuni casi di Stripe Checkout in cui la pagina di pagamento esterna viene abbandonata.

Se hai verificato che non ci sono eventi dell'endpoint webhook falliti sul tuo endpoint allora puoi disabilitare la notifica di configurazione seguendo i passaggi seguenti.

Posso disabilitare le notifiche di configurazione dei webhook?

Come accennato in precedenza, è altamente raccomandato configurare correttamente e mantenere abilitato il tuo endpoint webhook. Tuttavia, a tuo rischio, se non desideri essere avvisato di potenziali errori di configurazione o eventi ricevuti in modo errato, puoi rifiutare permanentemente la notifica in WP Simple Pay → Impostazioni → Stripe → Webhook facendo clic su Non mostrare più.