Webhooks

Inleiding

Een webhook is een internetadres (een URL) van uw organisatie: dat van uw server, uw CRM of een tool zoals Make of Zapier. Zodra er op Donoor een gebeurtenis plaatsvindt, stuurt Donoor naar dit adres een HTTPS POST-verzoek dat de gebeurtenis in JSON-formaat beschrijft.

Elk bericht wordt ondertekend met een geheim dat alleen u kent: zo kan uw server controleren of het echt van Donoor komt en niet is gewijzigd. Als uw server niet antwoordt, probeert Donoor het ongeveer 28 uur lang automatisch opnieuw.

Snel aan de slag

Reken op een kwartiertje om uw eerste bericht te ontvangen.

1. 1

   Bereid een ontvangstadres voor

   Een https-adres dat bereikbaar is vanaf internet, op uw server of in een tool zoals Make of Zapier. Om te testen zonder iets te installeren, volstaat een gratis adres van webhook.site.

2. 2

   Voeg het toe in uw dashboard

   Instellingen › Webhooks › Adres toevoegen. Geef het een beschrijving en kies de gebeurtenissen die u wilt ontvangen (standaard alle).

3. 3

   Kopieer het geheim

   Het begint met whsec_. Bewaar het in de configuratie van uw server, nooit in een webpagina of in een openbare coderepository.

4. 4

   Controleer de handtekening en antwoord 200

   Uw server controleert de header Donoor-Signature en antwoordt vervolgens binnen 10 seconden met een 2xx-code. De kant-en-klare code vindt u verderop, in Node.js, PHP en Python.

5. 5

   Verstuur een testbericht

   Knop Test versturen, of Gebeurtenis simuleren om een willekeurige van de 28 gebeurtenissen met fictieve gegevens te ontvangen. Controleer daarna het resultaat in het verzendlogboek.

Alleen gebeurtenissen die plaatsvinden na het toevoegen van uw eerste adres worden verstuurd: de geschiedenis wordt niet opnieuw verstuurd. De berichten bevatten het e-mailadres en de naam van de donateurs: alleen de verantwoordelijke en de beheerders van de organisatie kunnen de webhooks beheren, en de verantwoordelijke ontvangt een e-mail telkens wanneer een adres wordt toegevoegd of gewijzigd.

Lijst van gebeurtenissen

Elk adres ontvangt de gebeurtenissen die u hebt aangevinkt. De kolom ‘Inhoud’ geeft aan welke objecten in data staan; ze worden beschreven in het deel Objecten.

Een betaalde bestelling activeert twee gebeurtenissen: order.confirmed (de bestelling) en payment.succeeded (het geld). Gebruik voor het meten van uw conversies alleen payment.succeeded; voor het beheren van uw inschrijvingen alleen order.confirmed. Abonneer elk adres uitsluitend op de gebeurtenissen die het nodig heeft.

Berichten worden meestal binnen twee minuten na de gebeurtenis verstuurd: Donoor wacht tot alle informatie definitief is (uitbetaald bedrag, kosten…) voordat het bericht vertrekt.

Opbouw van een bericht

Elk bericht is een POST-verzoek waarvan de JSON-body, gecodeerd in UTF-8, altijd dezelfde omhulling heeft. Alleen de inhoud van data verschilt per type gebeurtenis. De veldnamen zijn in het Engels, zoals bij Stripe of HelloAsso.

Voorbeelden van berichten

{
  "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
    }
  }
}

Objecten

De objecten die in data kunnen voorkomen. Een veld zonder waarde is null. Datums staan in ISO 8601-formaat, in UTC.

Alle bedragen zijn in euro, met twee decimalen; de velden …_cents geven hetzelfde bedrag in centen. Het gaat om de bedragen van de organisatie: de vrijwillige bijdrage die een donateur aan Donoor geeft, is er nooit in opgenomen.

HTTP-headers

Elk verzoek bevat deze headers. Namen van HTTP-headers zijn niet hoofdlettergevoelig: uw server kan ze in kleine letters ontvangen.

De handtekening controleren

Iedereen kan een verzoek naar uw adres sturen: controleer daarom altijd de handtekening voordat u een bericht vertrouwt. De header Donoor-Signature bevat het tijdstempel van verzending (t, in seconden) en één of twee v1-handtekeningen. Elke handtekening is een HMAC-SHA256, in hexadecimale notatie, van de tekst ‘tijdstempel + punt + ruwe body’, berekend met uw geheim.

Donoor-Signature: t=1792300000,v1=f0f590ea41b7f691921bb57c47f593d785d4e4d7d6c14f947848cb9d2d471bdf

1. 1

   Lees de RUWE body van het verzoek, byte voor byte, vóór elke JSON-decodering.

2. 2

   Haal t en alle v1-waarden op uit de header Donoor-Signature.

3. 3

   Bereken HMAC-SHA256 met uw geheim (inclusief whsec_) over t + ‘.’ + body en vergelijk het resultaat met elke v1 via een vergelijking in constante tijd. Er hoeft er maar één overeen te komen.

4. 4

   Weiger het bericht als t meer dan 5 minuten afwijkt van uw klok: zo kan een onderschept bericht later niet opnieuw worden afgespeeld.

// Node.js (Express) — de RUWE body is onmisbaar voor de handtekening
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(); // snel antwoorden, daarna verwerken
  traiter(evenement);    // de gebeurtenis verwerken; negeren als de id al eerder is gezien
});

Controlevoorbeeld

Om uw code te testen zonder op een echt bericht te wachten: met deze waarden moet u precies deze handtekening krijgen.

De meest voorkomende fout: de JSON ondertekenen nadat deze is gedecodeerd en opnieuw gecodeerd. De kleinste spatie of de volgorde van de sleutels verandert de handtekening. Onderteken altijd de body precies zoals die is ontvangen.

Het geheim wijzigen

Als iemand anders uw geheim mogelijk heeft gezien, vervang het dan: Instellingen › Webhooks › Geheim › Geheim wijzigen.

Gedurende 24 uur worden de berichten ondertekend met het oude ÉN het nieuwe geheim: de header bevat dan twee v1-waarden. Installeer het nieuwe geheim binnen deze termijn op uw server; daarna werkt alleen nog het nieuwe.

Donoor bewaart het geheim versleuteld. Het wordt alleen getoond aan de verantwoordelijken en beheerders van de organisatie.

Geaccepteerde adressen

• Alleen https-adressen, met een geldig certificaat.
• Poort 443 (de standaardpoort) of 8443.
• Het adres moet bereikbaar zijn vanaf internet: lokale of privéadressen (localhost, intern netwerk) worden geweigerd.
• Omleidingen worden niet gevolgd: een 3xx-antwoord telt als mislukking. Geef het uiteindelijke adres op.
• Donoor verstuurt niet vanaf een vaste lijst IP-adressen: filter niet op IP, maar controleer de handtekening.

Een bericht beantwoorden

Antwoord binnen 10 seconden met een 2xx-code (200, 201, 204…). De inhoud van uw antwoord wordt niet gelezen, maar het begin ervan wordt in uw verzendlogboek getoond om u te helpen bij het debuggen.

Eerst antwoorden, dan verwerken: sla het bericht op, antwoord 200 en voer de langdurige verwerkingen (aanroep naar Google Ads, versturen van een e-mail…) daarna op de achtergrond uit.

Nieuwe pogingen en pauzeren

Wanneer een verzending mislukt, probeert Donoor het automatisch opnieuw: in totaal 8 pogingen, gespreid over ongeveer 28 uur.

1. 1e verzending
2. +1 min
3. +5 min
4. +30 min
5. +2 h
6. +5 h
7. +10 h
8. +10 h

• Na de 8e poging wordt het bericht opgegeven en ontvangt de organisatie een e-mail (maximaal één e-mail per adres per dag).
• Een adres dat 3 dagen lang geen enkel bericht accepteert, wordt automatisch gepauzeerd, met een e-mail ter melding. U activeert het opnieuw met één klik in het dashboard.
• Elk bericht in het logboek kan 30 dagen lang handmatig opnieuw worden verstuurd: knop Opnieuw versturen.

Duplicaten en volgorde

Dezelfde gebeurtenis kan meer dan eens binnenkomen: uw server heeft het bericht verwerkt maar het antwoord is verloren gegaan, of iemand heeft op Opnieuw versturen geklikt. De gebeurtenis behoudt dan dezelfde id: sla de al verwerkte id's op en negeer de id's die u al kent.

De volgorde van aankomst is niet gegarandeerd: bij een nieuwe poging kan een terugbetaling vóór de oorspronkelijke betaling binnenkomen. Ga uit van het veld created en de statussen van de objecten, niet van de volgorde van ontvangst.

Voor een advertentieconversie volstaat conversion_id: Google en Meta negeren zelf een conversie die al met dezelfde identificatie is ontvangen.

Limieten

Uw campagnes meten

Het bericht payment.succeeded geeft u het bedrag, de valuta, de conversie-identificatie en de parameters van de oorspronkelijke advertentie. Uw server geeft de conversie vervolgens door aan het advertentieplatform: dit is betrouwbaar, zelfs wanneer de browser cookies of trackers blokkeert.

Voorbeeld: een donatie doorgegeven aan 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
    }
  }]
}

Herkomst van betalingen

Voeg uw trackingparameters toe aan de link van uw advertenties, of die nu naar uw Donoor-pagina leidt of naar de pagina van uw website waarop de Donoor-widget staat:

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

• Alle parameters van de link blijven bewaard tot aan de betaling, zelfs als de donateur de betaalpagina in een nieuw tabblad opent.
• Ze komen terecht in data.attribution van payment.succeeded en van de andere gebeurtenissen van dezelfde betaling (terugbetaling, geschil, maandelijkse donatie).
• Bij de verlenging van een maandelijkse donatie is de herkomst die van de eerste betaling.
• Parameters die op gevoelige gegevens lijken (e-mailadres, wachtwoord, token, telefoonnummer, IBAN…) en technische parameters van Donoor worden verwijderd. Maximaal 25 parameters, 300 tekens per waarde.
• attribution is null wanneer de donateur niet via een link met parameters is binnengekomen.

Toestemming

attribution.marketing_consent geeft aan of de donateur advertentiecookies op Donoor heeft geaccepteerd: true, false, of null als dit onbekend is.

In Europa vragen Google en Meta om deze keuze te respecteren (toestemmingsmodus van Google, AVG). Uw organisatie blijft verantwoordelijk voor het gebruik dat zij van deze gegevens maakt: verstuur niet het e-mailadres van een donateur die heeft geweigerd, en vermeld deze verwerking in uw privacybeleid.

Tests, simulaties en logboek

De knop Test versturen, bij elk adres, verstuurt onmiddellijk een test.ping-gebeurtenis die net als de andere is ondertekend. Hiermee controleert u of uw server bereikbaar is en of uw handtekeningcontrole klopt.

De knop Gebeurtenis simuleren bij elk adres verstuurt een willekeurige van de 28 gebeurtenissen in het exacte formaat, met fictieve gegevens en livemode op false, alleen naar dat adres. Een voorbeeld toont het bericht vóór het versturen. Er wordt niets betaald en er worden geen echte gegevens verstuurd.

Om rustig te ontwikkelen, vinkt u Testadres aan in het venster van het adres: het ontvangt dan alleen simulaties en testberichten, nooit echte gebeurtenissen. Koppel er de ontwikkelserver van uw team aan en houd een ander adres voor productie.

Het verzendlogboek toont elk bericht van de afgelopen 30 dagen: gebeurtenis, status, aantal pogingen, HTTP-code en begin van het antwoord van uw server, en de exacte verstuurde inhoud. Filter op geslaagd, mislukt of in behandeling, en verstuur een bericht opnieuw met één klik.

Testomgeving

De simulator volstaat om uw webhooks te ontwikkelen. Om ook het volledige betaaltraject te testen (donatiepagina, testkaart, bewijs), biedt Donoor een afzonderlijke testomgeving op sandbox.donoor.org. De pagina's worden niet geïndexeerd door zoekmachines.

1. Maak een organisatieaccount aan via sandbox.donoor.org (knop Mijn organisatie registreren): er staan geen echte gegevens in.
2. Koppel Stripe via Instellingen › Inzamelproces. In testmodus accepteert Stripe fictieve gegevens (sms-code: 000000): een echte bankrekening is niet nodig.
3. Uw testbetaalpagina staat meteen online, bijvoorbeeld sandbox.donoor.org/pay/uw-organisatie, net als uw test-inzamelingsacties, -ticketverkoop en -winkels.
4. Voeg uw webhookadres toe via Instellingen › Webhooks, net als in productie.
5. Doe een donatie op deze pagina met de testkaart 4242 4242 4242 4242 (willekeurige toekomstige datum, willekeurige code): u ontvangt echte ondertekende berichten, met livemode op false. Het testgeheim verschilt van dat van productie.

Versies van het formaat

Het veld api_version geeft de versie van het berichtformaat aan. Deze wijzigt alleen bij een incompatibele wijziging (een hernoemd of verwijderd veld, een gewijzigde betekenis), die vooraf wordt aangekondigd.

Donoor kan, zonder van versie te veranderen, nieuwe gebeurtenissen en nieuwe velden toevoegen: uw code moet negeren wat hij niet kent.

Problemen oplossen