Webhook

Presentazione

Un webhook è un indirizzo internet (un URL) che appartiene alla vostra organizzazione: quello del vostro server, del vostro CRM o di uno strumento come Make o Zapier. Non appena si verifica un evento su Donoor, Donoor invia a questo indirizzo una richiesta HTTPS POST che descrive l'evento in formato JSON.

Ogni messaggio è firmato con un segreto che conoscete solo voi: in questo modo il vostro server può verificare che provenga davvero da Donoor e che non sia stato modificato. Se il vostro server non risponde, Donoor riprova automaticamente per circa 28 ore.

Avvio rapido

Calcolate una quindicina di minuti per ricevere il vostro primo messaggio.

1. 1

   Preparate un indirizzo di ricezione

   Un indirizzo https raggiungibile da Internet, sul vostro server o in uno strumento come Make o Zapier. Per provare senza installare nulla, basta un indirizzo gratuito di webhook.site.

2. 2

   Aggiungetelo nella vostra dashboard

   Impostazioni › Webhook › Aggiungi un indirizzo. Assegnategli una descrizione e scegliete gli eventi da ricevere (tutti, per impostazione predefinita).

3. 3

   Copiate il segreto

   Inizia con whsec_. Conservatelo nella configurazione del vostro server, mai in una pagina web o in un repository di codice pubblico.

4. 4

   Verificate la firma e rispondete 200

   Il vostro server verifica l'header Donoor-Signature e poi risponde con un codice 2xx in meno di 10 secondi. Il codice pronto da copiare si trova più in basso, in Node.js, PHP e Python.

5. 5

   Inviate un messaggio di prova

   Pulsante Invia un test, oppure Simula un evento per ricevere uno qualsiasi dei 28 eventi con dati fittizi. Verificate poi il risultato nel registro degli invii.

Vengono inviati solo gli eventi che si verificano dopo l'aggiunta del vostro primo indirizzo: lo storico non viene reinviato. I messaggi contengono l'e-mail e il nome dei donatori: solo il responsabile e gli amministratori dell'organizzazione possono gestire i webhook, e il responsabile viene avvisato via e-mail a ogni indirizzo aggiunto o modificato.

Elenco degli eventi

Ogni indirizzo riceve gli eventi che avete selezionato. La colonna «Contenuto» indica gli oggetti presenti in data, descritti nella sezione Oggetti.

Un ordine pagato genera due eventi: order.confirmed (l'ordine) e payment.succeeded (il denaro). Per misurare le vostre conversioni, utilizzate solo payment.succeeded; per gestire i vostri iscritti, solo order.confirmed. Iscrivete ogni indirizzo solo agli eventi di cui avete bisogno.

I messaggi partono in genere meno di due minuti dopo il fatto: Donoor attende che tutte le informazioni siano definitive (importo versato, commissioni…) prima di inviarli.

Struttura di un messaggio

Ogni messaggio è una richiesta POST il cui corpo JSON, codificato in UTF-8, ha sempre la stessa struttura esterna. Cambia solo il contenuto di data, a seconda del tipo di evento. I nomi dei campi sono in inglese, come in Stripe o HelloAsso.

Esempi di messaggi

{
  "id": "evt_9mK2xQpL4vR8sT1w",
  "object": "event",
  "type": "payment.succeeded",
  "api_version": "2026-10-17",
  "created": "2026-10-17T14:02:11.000Z",
  "livemode": true,
  "organization": {
    "id": 1234,
    "name": "Les Amis du Quartier"
  },
  "data": {
    "payment": {
      "id": 32631,
      "conversion_id": "32631",
      "order_id": null,
      "status": "succeeded",
      "amount": 50.6,
      "amount_cents": 5060,
      "net_amount": 49.3,
      "fees_covered_amount": 0.6,
      "provider_fee_amount": 1.3,
      "currency": "EUR",
      "refunded_amount": 0,
      "kind": "donation",
      "channel": "online",
      "form": null,
      "recurring": {
        "interval": "month",
        "sequence": "first",
        "subscription_id": 812
      },
      "payment_provider": "stripe",
      "payment_method": "card",
      "wallet": "apple_pay",
      "provider_reference": "pi_3UQZvoFXPodLa3BZ2HKqlaEw",
      "donor": {
        "email": "amina.k@exemple.fr",
        "name": "Amina K.",
        "anonymous": false
      },
      "created": "2026-10-17T14:01:02.000Z"
    },
    "attribution": {
      "parameters": {
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "ramadan-2027",
        "gclid": "Cj0KCQjw8eTFBhCXARIsAIkiuOz"
      },
      "landing_page": "https://www.mon-association.org/faire-un-don",
      "marketing_consent": true
    }
  }
}

Oggetti

Gli oggetti che possono comparire in data. Un campo senza valore vale null. Le date sono in formato ISO 8601, in UTC.

Tutti gli importi sono in euro, con due decimali; i campi …_cents riportano lo stesso importo in centesimi. Gli importi sono quelli dell'organizzazione: il contributo facoltativo che un donatore lascia a Donoor non vi compare mai.

Header HTTP

Ogni richiesta contiene questi header. I nomi degli header HTTP non distinguono tra maiuscole e minuscole: il vostro server può riceverli in minuscolo.

Verificare la firma

Chiunque può inviare una richiesta al vostro indirizzo: verificate quindi sempre la firma prima di fidarvi di un messaggio. L'header Donoor-Signature contiene la marca temporale dell'invio (t, in secondi) e una o due firme v1. Ogni firma è un HMAC-SHA256, scritto in esadecimale, del testo «marca temporale + punto + corpo grezzo», calcolato con il vostro segreto.

Donoor-Signature: t=1792300000,v1=f0f590ea41b7f691921bb57c47f593d785d4e4d7d6c14f947848cb9d2d471bdf

1. 1

   Leggete il corpo GREZZO della richiesta, byte per byte, prima di qualsiasi decodifica JSON.

2. 2

   Recuperate t e tutti i valori v1 dall'header Donoor-Signature.

3. 3

   Calcolate l'HMAC-SHA256 con il vostro segreto (whsec_ compreso) su t + «.» + corpo, quindi confrontate il risultato con ogni v1 mediante un confronto a tempo costante. Ne deve corrispondere uno solo.

4. 4

   Rifiutate il messaggio se t si discosta di oltre 5 minuti dal vostro orologio: così un messaggio intercettato non può essere riprodotto in seguito.

// Node.js (Express) — il corpo GREZZO è indispensabile per la firma
import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.DONOOR_WEBHOOK_SECRET; // whsec_…
const app = express();

app.post("/webhooks/donoor", express.raw({ type: "application/json" }), (req, res) => {
  const entete = req.get("Donoor-Signature") ?? "";
  const t = /t=(\d+)/.exec(entete)?.[1];
  const signatures = [...entete.matchAll(/v1=([0-9a-f]{64})/g)].map((m) => m[1]);
  const attendue = crypto.createHmac("sha256", SECRET).update(`${t}.${req.body}`).digest("hex");

  const valide = signatures.some((s) =>
    crypto.timingSafeEqual(Buffer.from(s, "hex"), Buffer.from(attendue, "hex")));
  const recent = t && Math.abs(Date.now() / 1000 - Number(t)) < 300;
  if (!valide || !recent) return res.status(400).end();

  const evenement = JSON.parse(req.body.toString("utf8"));
  res.status(200).end(); // rispondere subito, elaborare dopo
  traiter(evenement);    // elaborare l'evento; ignorarlo se il suo id è già stato visto
});

Esempio di verifica

Per testare il vostro codice senza attendere un messaggio reale: con questi valori dovete ottenere esattamente questa firma.

L'errore più frequente: firmare il JSON dopo averlo decodificato e ricodificato. Il minimo spazio o l'ordine delle chiavi cambia la firma. Firmate sempre il corpo esattamente come è stato ricevuto.

Cambiare il segreto

Se il vostro segreto potrebbe essere stato visto da qualcun altro, sostituitelo: Impostazioni › Webhook › Segreto › Cambia il segreto.

Per 24 ore i messaggi vengono firmati con il vecchio E con il nuovo segreto: l'header contiene quindi due valori v1. Installate il nuovo segreto sul vostro server entro questo periodo; dopodiché funziona solo il nuovo.

Donoor conserva il segreto in forma cifrata. Viene mostrato solo ai responsabili e agli amministratori dell'organizzazione.

Indirizzi accettati

• Solo indirizzi https, con un certificato valido.
• Porta 443 (quella predefinita) o 8443.
• L'indirizzo deve essere raggiungibile da Internet: gli indirizzi locali o privati (localhost, rete interna) vengono rifiutati.
• I reindirizzamenti non vengono seguiti: una risposta 3xx conta come un errore. Indicate l'indirizzo finale.
• Donoor non invia da un elenco fisso di indirizzi IP: non filtrate per IP, verificate la firma.

Rispondere a un messaggio

Rispondete con un codice 2xx (200, 201, 204…) in meno di 10 secondi. Il contenuto della vostra risposta non viene letto, ma la sua parte iniziale viene mostrata nel registro degli invii per aiutarvi nel debug.

Prima rispondete, poi elaborate: registrate il messaggio, rispondete 200, quindi eseguite le elaborazioni lunghe (chiamata a Google Ads, invio di e-mail…) in background.

Nuovi tentativi e messa in pausa

Quando un invio non va a buon fine, Donoor riprova automaticamente: 8 tentativi in totale, nell'arco di circa 28 ore.

1. 1° invio
2. +1 min
3. +5 min
4. +30 min
5. +2 h
6. +5 h
7. +10 h
8. +10 h

• Dopo l'8° tentativo, il messaggio viene abbandonato e l'organizzazione viene avvisata via e-mail (al massimo un'e-mail per indirizzo e per giorno).
• Un indirizzo che non accetta alcun messaggio per 3 giorni viene messo in pausa automaticamente, con un'e-mail di avviso. Si riattiva con un clic dalla dashboard.
• Qualsiasi messaggio del registro può essere reinviato manualmente per 30 giorni: pulsante Reinvia.

Duplicati e ordine

Uno stesso evento può arrivare più di una volta: il vostro server ha elaborato il messaggio ma la sua risposta è andata persa, oppure qualcuno ha cliccato su Reinvia. L'evento mantiene allora lo stesso id: registrate gli id già elaborati e ignorate quelli che conoscete.

L'ordine di arrivo non è garantito: in caso di nuovo tentativo, un rimborso può arrivare prima del pagamento di origine. Basatevi sul campo created e sugli stati degli oggetti, non sull'ordine di ricezione.

Per una conversione pubblicitaria basta conversion_id: Google e Meta ignorano autonomamente una conversione già ricevuta con lo stesso identificativo.

Limiti

Misurare le vostre campagne

Il messaggio payment.succeeded vi fornisce l'importo, la valuta, l'identificativo di conversione e i parametri dell'annuncio di origine. Il vostro server trasmette poi la conversione alla piattaforma pubblicitaria: il metodo è affidabile anche quando il browser blocca i cookie o i tracker.

Esempio: una donazione trasmessa a GA4

POST https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXX&api_secret=…

{
  "client_id": "donoor.32631",
  "events": [{
    "name": "purchase",
    "params": {
      "transaction_id": "32631",   // data.payment.conversion_id
      "value": 50.6,               // data.payment.amount
      "currency": "EUR",           // data.payment.currency
      "campaign": "ramadan-2027"   // data.attribution.parameters.utm_campaign
    }
  }]
}

Provenienza dei pagamenti

Aggiungete i vostri parametri di tracciamento al link dei vostri annunci, sia che porti alla vostra pagina Donoor sia alla pagina del vostro sito che mostra il widget Donoor:

https://donoor.org/pay/mon-association?utm_source=google&utm_campaign=ramadan-2027&gclid=Cj0KCQjw…

• Tutti i parametri del link vengono conservati fino al pagamento, anche se il donatore apre la pagina di pagamento in una nuova scheda.
• Arrivano in data.attribution di payment.succeeded e degli altri eventi dello stesso pagamento (rimborso, contestazione, donazione mensile).
• Per il rinnovo di una donazione mensile, la provenienza è quella del primo pagamento.
• I parametri che sembrano dati sensibili (e-mail, password, token, telefono, IBAN…) e i parametri tecnici di Donoor vengono scartati. Al massimo 25 parametri, 300 caratteri per valore.
• attribution vale null quando il donatore non è arrivato tramite un link con parametri.

Consenso

attribution.marketing_consent indica se il donatore ha accettato i cookie pubblicitari su Donoor: true, false, oppure null se non è noto.

In Europa, Google e Meta chiedono di rispettare questa scelta (Modalità di consenso di Google, GDPR). La vostra organizzazione resta responsabile dell'uso che fa di questi dati: non inviate l'e-mail di un donatore che ha rifiutato e ricordatevi di menzionare questo trattamento nella vostra informativa sulla privacy.

Test, simulazioni e registro

Il pulsante Invia un test, presente su ogni indirizzo, invia immediatamente un evento test.ping firmato come gli altri. Serve a verificare che il vostro server sia raggiungibile e che la vostra verifica della firma sia corretta.

Il pulsante Simula un evento, su ogni indirizzo, invia uno qualsiasi dei 28 eventi nel formato esatto, con dati fittizi e livemode impostato su false, solo a quell'indirizzo. Un'anteprima mostra il messaggio prima dell'invio. Nessun pagamento viene effettuato e nessun dato reale viene inviato.

Per sviluppare in tranquillità, attivate Indirizzo di test nella finestra dell'indirizzo: riceverà allora solo simulazioni e messaggi di test, mai eventi reali. Collegatevi il server di sviluppo del vostro team e tenete un altro indirizzo per la produzione.

Il registro degli invii mostra ogni messaggio degli ultimi 30 giorni: evento, stato, numero di tentativi, codice HTTP e inizio della risposta del vostro server, oltre al contenuto esatto inviato. Filtrate per riusciti, non riusciti o in attesa e reinviate un messaggio con un clic.

Ambiente di test

Il simulatore basta per sviluppare i vostri webhook. Per testare anche il percorso di pagamento completo (pagina di donazione, carta di test, ricevuta), Donoor mette a disposizione un ambiente di test separato su sandbox.donoor.org. Le sue pagine non sono indicizzate dai motori di ricerca.

1. Create un account di organizzazione da sandbox.donoor.org (pulsante Registra la mia organizzazione): non contiene alcun dato reale.
2. Collegate Stripe in Impostazioni › Processo di raccolta. In modalità test, Stripe accetta informazioni fittizie (codice SMS: 000000): non serve alcun conto bancario reale.
3. La vostra pagina di pagamento di test è subito online, ad esempio sandbox.donoor.org/pay/la-vostra-organizzazione, come le vostre raccolte fondi, biglietterie e negozi di test.
4. Aggiungete il vostro indirizzo webhook in Impostazioni › Webhook, come in produzione.
5. Fate una donazione su questa pagina con la carta di test 4242 4242 4242 4242 (qualsiasi data futura, qualsiasi codice): riceverete veri messaggi firmati, con livemode impostato su false. Il segreto di test è diverso da quello di produzione.

Versioni del formato

Il campo api_version indica la versione del formato del messaggio. Cambia solo in caso di evoluzione incompatibile (un campo rinominato o eliminato, un significato modificato), annunciata in anticipo.

Senza cambiare versione, Donoor può aggiungere nuovi eventi e nuovi campi: il vostro codice deve ignorare ciò che non conosce.

Risoluzione dei problemi