Webhook
Collegare i vostri strumenti con i webhook
Il corso per collegare Donoor ai vostri strumenti, con o senza sviluppatore, e seguire ogni messaggio inviato.
- 5 moduli · 10 min
- 1 scheda pratica da scaricare
- 13 articoli per approfondire
Presentazione
Il contenuto del corso
Inviate automaticamente ogni donazione, adesione, biglietto o ordine al vostro CRM, alla vostra contabilità o ai vostri strumenti pubblicitari. Misurate finalmente le vostre campagne Google Ads e Meta, donazione per donazione.
- Creare un indirizzo webhook e scegliere gli eventi da ricevere
- Testare l'invio, leggere il registro e inviare di nuovo un messaggio
- Risalire alla provenienza pubblicitaria di ogni donazione per misurare le vostre campagne
Modulo 1
Creare il vostro primo webhook
Indicate a Donoor l'indirizzo del vostro strumento: a ogni evento, riceverà lì un messaggio firmato.
Contenuto del modulo · 2 min
- Che cos'è un webhook e a cosa serve
- Preparare un indirizzo di ricezione (per provare: webhook.site)
- Scegliere gli eventi, suddivisi per categoria
- Copiare il segreto di firma
Contenuti che potrebbero interessarvi
Vedi la guida passo dopo passo (5 passaggi)
- 1
Preparate l'indirizzo di ricezione
È l'indirizzo https del vostro server, del vostro CRM o di uno scenario Make o Zapier. Per provare senza installare nulla, aprite webhook.site: compare un indirizzo gratuito, copiatelo.
- 2
Aprite le impostazioni
Nella dashboard, cliccate sul nome della vostra organizzazione in basso a sinistra, poi su Impostazioni e sulla scheda Webhooks.
- 3
Aggiungete l'indirizzo
Cliccate su Aggiungi un indirizzo, incollate l'indirizzo e dategli una descrizione che vi sia chiara, per esempio «Conversioni Google Ads».
- 4
Scegliete gli eventi
Gli eventi sono suddivisi per categoria: pagamenti, donazioni mensili, ordini, soci e biglietti, ricevute di donazione, versamenti… Nel dubbio, lasciate tutto selezionato, poi cliccate su Aggiungi.
- 5
Copiate il segreto
Una finestra mostra il segreto di firma (inizia con whsec_). Cliccate su Copia e trasmettetelo al vostro team tecnico: dimostra che i messaggi provengono davvero da Donoor. Potrete visualizzarlo di nuovo in qualsiasi momento.
Consiglio
Solo il proprietario e gli amministratori dell'organizzazione possono gestire i webhook, e il proprietario riceve un'email a ogni indirizzo aggiunto o modificato: nessuno può deviare i vostri dati di nascosto.
Modulo 2
Testare, simulare e seguire gli invii
Verificate con un clic che il vostro strumento riceva i messaggi, simulate qualsiasi evento senza un pagamento reale, poi seguite ogni invio nel registro.
Contenuto del modulo · 2 min
- Inviare un messaggio di prova
- Simulare uno qualsiasi dei 28 eventi
- Leggere il registro degli invii
- Aprire un invio: risposta del vostro server e messaggio esatto
- Vedere arrivare il messaggio sul server
Contenuti che potrebbero interessarvi
Vedi la guida passo dopo passo (5 passaggi)
- 1
Inviate un messaggio di prova
Sulla scheda del vostro indirizzo, cliccate su Invia un test. Un messaggio di prova parte subito, firmato come quelli reali.
- 2
Simulate un evento reale
Pulsante Simula un evento: scegliete ad esempio «Pagamento confermato» o «Ingresso scansionato». Un'anteprima mostra il messaggio, poi Donoor lo invia con dati fittizi (livemode false), senza alcun pagamento reale. Per il vostro server di sviluppo, aggiungete un indirizzo attivando Indirizzo di test: riceverà solo queste simulazioni.
- 3
Guardate il registro
Più in basso, il Registro degli invii elenca ogni messaggio degli ultimi 30 giorni con il suo stato: riuscito, non riuscito o in attesa. Filtrate con i pulsanti sopra l'elenco.
- 4
Aprite un invio
Cliccate su una riga: vedete la risposta del vostro server (codice 200 se va tutto bene), ogni tentativo con il suo orario e il messaggio esatto inviato, da copiare se serve.
- 5
Verificate sul server
Nel vostro strumento (o su webhook.site), il messaggio è arrivato con l'intestazione Donoor-Signature: è quella che il vostro team tecnico verifica.
Modulo 3
Seguire la provenienza di ogni donazione
Scoprite quale annuncio ha portato ogni donatore: il messaggio della donazione contiene i parametri del vostro annuncio.
Contenuto del modulo · 2 min
- Aggiungere parametri di tracciamento ai vostri link (utm, gclid…)
- Cosa contiene il messaggio di una donazione
- Trasmettere la conversione a Google Ads, GA4 o Meta
- Ritrovare ogni donazione nel registro
Contenuti che potrebbero interessarvi
Vedi la guida passo dopo passo (4 passaggi)
- 1
Aggiungete i vostri parametri di tracciamento
Nei vostri annunci, aggiungete al vostro link Donoor i parametri abituali: utm_source, utm_campaign… Google Ads aggiunge da solo il gclid se il tagging automatico è attivo. I parametri vengono conservati fino al pagamento, anche se il donatore cambia scheda.
- 2
Il donatore fa la sua donazione
Per lui non cambia nulla: la pagina di donazione è la stessa. Funziona anche con il widget integrato nel vostro sito.
- 3
Il messaggio arriva
Meno di due minuti dopo il pagamento, il vostro strumento riceve payment.succeeded: importo, donatore, identificativo di conversione e, in attribution, i parametri dell'annuncio di origine.
- 4
Trasmettete la conversione
Il vostro server, o uno scenario Make o Zapier, invia la conversione a Google Ads, GA4 o Meta con l'importo e l'identificativo di conversione. Le vostre campagne vengono misurate donazione per donazione, anche quando il browser blocca i cookie.
Consiglio
Il messaggio indica anche se il donatore ha accettato i cookie pubblicitari (marketing_consent): rispettate questa scelta prima di inviare i suoi dati a Google o Meta.
Modulo 4
Gestire i vostri webhook ogni giorno
Modificate i vostri indirizzi, metteteli in pausa, cambiate il segreto e sappiate come reagire quando il vostro server non risponde più.
Contenuto del modulo · 2 min
- Scegliere con precisione gli eventi di un indirizzo
- Mettere in pausa e riattivare
- Cambiare il segreto senza interrompere nulla
- Server fuori uso: nuovi tentativi automatici e reinvio
Contenuti che potrebbero interessarvi
Vedi la guida passo dopo passo (5 passaggi)
- 1
Modificate un indirizzo
La matita apre la finestra dell'indirizzo: cambiate la sua descrizione o i suoi eventi. I pulsanti Seleziona tutto e Deseleziona tutto agiscono categoria per categoria.
- 2
Mettete in pausa
Metti in pausa interrompe gli invii verso questo indirizzo, per esempio durante una manutenzione. Riattiva li fa ripartire.
- 3
Cambiate il segreto se serve
Pulsante Segreto, poi Cambia il segreto. Il vecchio resta valido per 24 ore, il tempo che il vostro team installi quello nuovo.
- 4
Se il vostro server non risponde
Donoor riprova automaticamente 8 volte nell'arco di circa 28 ore; il registro mostra l'orario del prossimo tentativo. Dopo l'ultimo, ricevete un avviso via email. Un indirizzo che non riceve correttamente i messaggi per 3 giorni viene messo in pausa automaticamente.
- 5
Inviate di nuovo un messaggio
Una volta riparato il vostro server, aprite l'invio nel registro e cliccate su Invia di nuovo: lo stesso messaggio riparte subito.
Modulo 5
La guida per il vostro team tecnico
Tutto ciò che serve alla persona che collega il vostro server: formato dei messaggi, firma, nuovi tentativi e ambiente di test.
Contenuto del modulo · 2 min
- I 28 eventi e il contenuto di ogni messaggio
- Verificare la firma, con codice pronto da copiare in Node.js, PHP e Python
- Rispondere, nuovi tentativi, duplicati e limiti
- L'ambiente di test sandbox.donoor.org
Contenuti che potrebbero interessarvi
Vedi la guida passo dopo passo (3 passaggi)
- 1
Trasmettete la documentazione
Inviate al vostro team tecnico il link alla Documentazione tecnica dei webhook: descrive ogni evento e ogni campo.
- 2
Verificate ogni messaggio
Il server verifica l'intestazione Donoor-Signature con il segreto, poi risponde con un codice 200 in meno di 10 secondi. Un esempio svolto con valori concreti permette di testare il codice.
- 3
Testate senza rischi
Su sandbox.donoor.org, un ambiente di test separato e non indicizzato dai motori di ricerca, create un'organizzazione e collegate Stripe in modalità test (bastano informazioni fittizie). La vostra pagina di pagamento di test è subito online: fate donazioni fittizie con la carta 4242 4242 4242 4242 e ricevete veri messaggi, contrassegnati livemode false.
Domande? Vi rispondiamo
Serve uno sviluppatore per usare i webhook?
Non necessariamente. Con Make o Zapier, incollate in Donoor l'indirizzo del loro modulo «Webhook personalizzato», poi collegate i messaggi a Google Sheets, al vostro CRM o a Google Ads senza scrivere codice. Per un server vostro, serve qualcuno che sappia verificare la firma: la documentazione tecnica fornisce il codice pronto da copiare.
Come fare test senza pagamenti reali?
Dal vostro account: il pulsante Simula un evento invia uno qualsiasi dei 28 eventi con dati fittizi, e un indirizzo di test riceve solo queste simulazioni. Nulla da installare, nessuna nuova registrazione.
I webhook sono a pagamento?
No: sono gratuiti e aperti a tutte le organizzazioni, come il resto di Donoor.
Ricevo anche le donazioni passate?
No: vengono inviati solo gli eventi che avvengono dopo l'aggiunta del vostro primo indirizzo. Per lo storico, usate le esportazioni della dashboard.
I dati dei miei donatori sono protetti?
I messaggi partono solo verso indirizzi https, firmati con un segreto proprio di ogni indirizzo. Solo il proprietario e gli amministratori possono configurare i webhook, e il proprietario riceve un avviso via email a ogni modifica di indirizzo.
Cosa succede se il mio server è fuori uso?
Non si perde nulla: Donoor riprova per circa 28 ore, poi vi avvisa via email. Ogni messaggio resta 30 giorni nel registro e si invia di nuovo con un clic.
Una domanda? Parliamone.
30 minuti in videochiamata per scoprire Donoor, fare le vostre domande e configurare insieme la vostra organizzazione.
Gratuita e senza impegno