Webhook PayPal: configurazione e test

I webhook PayPal sono il sistema moderno di notifica server-to-server delle REST API: ogni volta che avviene un'evento (pagamento catturato, rimborso, contestazione) PayPal invia un POST JSON firmato al tuo endpoint. A differenza dell'IPN legacy, i webhook supportano firma HMAC verificabile, retry automatici e payload strutturati. Vediamo come configurarli, verificare la firma e testarli correttamente.

Anatomia di un webhook

Un webhook è composto da: un endpoint HTTPS del merchant, una app REST nel Developer Dashboard PayPal che genera webhook_id e client_id, una lista di eventi sottoscritti (PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.REFUNDED, ecc.), e un meccanismo di verifica firma tramite l'API /v1/notifications/verify-webhook-signature. La firma usa certificato X.509 emesso da PayPal con catena pubblica.

Eventi più utilizzati

Sono circa 90 gli eventi sottoscrivibili. I principali per un'e-commerce: PAYMENT.CAPTURE.COMPLETED (pagamento riuscito), PAYMENT.CAPTURE.DENIED (rifiutato), PAYMENT.CAPTURE.REFUNDED (rimborso), PAYMENT.CAPTURE.REVERSED (storno chargeback), CUSTOMER.DISPUTE.CREATED (apertura disputa), BILLING.SUBSCRIPTION.ACTIVATED e BILLING.SUBSCRIPTION.CANCELLED per abbonamenti. Sottoscrivi solo gli eventi che usi davvero: ogni evento è una richiesta in più al tuo server.

Procedura passo-passo

1. Accedi a developer.paypal.com con l'account Business.
2. Crea o seleziona un'app REST esistente.
3. Scorri fino alla sezione "Webhooks" e clicca su "Add Webhook".
4. Inserisci l'URL HTTPS del tuo endpoint (es. https://miosito.it/paypal/webhook).
5. Seleziona gli eventi da sottoscrivere.
6. Salva: PayPal genera un webhook_id univoco.
7. Implementa l'endpoint che riceve POST JSON.
8. Verifica la firma con /v1/notifications/verify-webhook-signature.
9. Processa l'evento solo se la firma è "SUCCESS".
10. Rispondi HTTP 200 in meno di 30 secondi.

Verifica della firma

PayPal include negli header HTTP: PAYPAL-TRANSMISSION-ID, PAYPAL-TRANSMISSION-TIME, PAYPAL-CERT-URL, PAYPAL-AUTH-ALGO, PAYPAL-TRANSMISSION-SIG. Per verificare la firma chiami POST a /v1/notifications/verify-webhook-signature passando questi header, il webhook_id e il payload originale. La risposta "verification_status: SUCCESS" autorizza il processing. Mai fidarti del payload senza verifica: chiunque conosca l'endpoint può inviare POST falsi.

Idempotenza e retry

PayPal riprova fino a 25 volte in 72 ore se non riceve risposta 2xx. Devi quindi gestire idempotenza: salva l'event_id (campo "id" nel payload) in una tabella unique e ignora eventi già processati. La logica tipica: ricevi webhook → verifica firma → cerca event_id in tabella → se nuovo, processa e salva; se già presente, rispondi 200 senza fare nulla. Senza idempotenza rischi addebiti doppi, mail multiple e ordini duplicati.

Testing con il Webhook Simulator

Il Developer Dashboard offre un simulatore: scegli evento, app, URL e PayPal invia un payload realistico. Usalo per testare la verifica della firma e la logica di processing senza dover generare transazioni vere. Il simulatore non valida firma né retry: per quelli serve testare in Sandbox con account buyer/seller reali. Strumenti utili: ngrok per esporre localhost durante lo sviluppo, webhook.site per ispezionare payload.

Errori comuni e come risolverli

• Endpoint HTTP non HTTPS: PayPal rifiuta. Usa HTTPS valido sempre.
• Verifica firma assente: rischio di processing di payload falsi. Implementa sempre la verifica.
• Risposta oltre 30 secondi: PayPal disabilita progressivamente l'endpoint. Scarica processing pesante in coda.
• Nessuna idempotenza: addebiti doppi a clienti. Salva event_id già processati.
• Firewall blocca PayPal: whitelist IP PayPal o disabilita challenge Cloudflare sull'endpoint.

Domande frequenti

D: Webhook sostituisce IPN?
R: Funzionalmente sì. PayPal raccomanda webhook per nuove integrazioni; IPN resta supportato per compatibilità.

D: Posso avere più endpoint webhook per la stessa app?
R: Sì, fino a 10 webhook diversi per app, ognuno con eventi differenti.

D: Come ricevo notifiche per dispute?
R: Sottoscrivi gli eventi della famiglia CUSTOMER.DISPUTE.*.

Consigli operativi e best practice

Per consolidare quanto visto nei paragrafi precedenti tieni a mente alcuni accorgimenti pratici che fanno la differenza nel quotidiano. Documenta sempre ogni passaggio della configurazione in un registro interno aziendale: serve sia per il team sia in caso di audit fiscale o di richiesta di chiarimenti da parte di PayPal. Conserva una copia delle ricevute, delle email transazionali e degli screenshot dei pannelli di amministrazione per almeno dieci anni, come richiesto dalla normativa civilistica italiana.

Pianifica una revisione trimestrale della tua integrazione PayPal: verifica le commissioni applicate, controlla i tassi di contestazione, leggi gli avvisi nel Centro Risoluzioni e aggiorna eventuali plugin o SDK obsoleti. Le aziende che fanno questo controllo regolare riducono del 40-60% gli incidenti operativi rispetto a chi gestisce PayPal in modo reattivo. Coinvolgi anche il team di customer service: spesso sono loro i primi a notare pattern di richieste che possono indicare problemi nascosti nel flusso di pagamento.

Infine, abituati a monitorare i tempi di risposta nelle dispute e nei reclami: PayPal premia i merchant che rispondono entro 24-48 ore con score reputazionali migliori, che si traducono in minori riserve, commissioni più favorevoli al raggiungimento dei volumi e un'esperienza più fluida in caso di controlli antifrode. La gestione proattiva è sempre meno costosa di quella reattiva, in PayPal come nel resto del business online.

Vale la pena ricordare che ogni implementazione PayPal va testata in ambiente Sandbox prima del passaggio in produzione: simulare ogni scenario (successo, errore, timeout, refund parziale, dispute) permette di intercettare i bug più subdoli senza rischio reale di addebiti errati a clienti veri. Investi almeno una giornata di test prima del go-live, soprattutto se la tua integrazione coinvolge più sistemi come gestionale, CRM, magazzino, sistema di spedizioni o cassa fisica.

Mantieni inoltre un canale di comunicazione diretto con il supporto merchant PayPal: per gli account Business con volumi rilevanti è possibile avere un'account manager dedicato che risponde via email o telefono per problematiche complesse. Per i merchant più piccoli c'è il supporto via chat e centro assistenza online, con tempi di risposta tra le 2 e le 24 ore. Documenta sempre il ticket number nelle comunicazioni interne per agevolare follow-up successivi.

Hai bisogno di aiuto?

Se vuoi integrare PayPal nel tuo sito con il team di G Tech Group, scrivici tramite il modulo di contatto.