Bouw verder op je stream.

Snel beginnen

Gebruik de API vanuit je eigen server of persoonlijke app. Alle endpoints zijn alleen-lezen en gebruiken JSON. De basis-URL is https://donolink.nl/api/v1.

1. Ga naar Instellingen → Developer → API keys. Geef je integratie een naam en kies een vervaldatum.
2. Kopieer de sleutel eenmalig en bewaar hem als DONOLINK_API_KEY in de geheime configuratie van je server.
3. Doe je eerste request. Zonder filters ontvang je maximaal 50 events, nieuwste eerst.

curl 'https://donolink.nl/api/v1/activity?limit=50' \
  -H "Authorization: Bearer $DONOLINK_API_KEY"

Voorbeeldresponse

{
  "data": [
    {
      "id": "evt_abcdefghijklmno",
      "type": "subscription",
      "platform": "twitch",
      "occurred_at": "2026-09-07T12:00:00.000Z",
      "recorded_at": "2026-09-07T12:00:00.000Z",
      "actor": {
        "name": "StreamFan"
      },
      "message": null,
      "value": 3,
      "unit": "months",
      "currency": null,
      "refunded_amount_cents": null
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": "OPAQUE_CURSOR"
  }
}

Authenticatie

Stuur je sleutel bij ieder request mee in de Authorization-header. Een sessiecookie, queryparameter of overlay-token geeft geen toegang tot deze API.

Authorization: Bearer dl_live_YOUR_SECRET_KEY

Je kiest een geldigheid van 30, 90 of 365 dagen. Je kunt maximaal 10 actieve sleutels hebben en één sleutel per minuut aanmaken. DonoLink bewaart alleen een SHA-256-hash; de volledige sleutel is alleen direct na aanmaken zichtbaar.

Gebruik een eigen sleutel per integratie. Maak voor rotatie eerst een nieuwe sleutel aan, werk je app bij en trek daarna de oude in. Een ingetrokken of verlopen sleutel werkt niet meer bij het volgende request.

Iedere sleutel heeft de vaste scope activity:read en is aan jouw account gebonden. Er zijn geen schrijf-, betaal- of beheerrechten. OAuth voor apps met meerdere klanten is nog niet beschikbaar.

Endpoints

Controleer welke streamer bij je sleutel hoort en wanneer de sleutel verloopt. Alleen het publieke profiel, de scope en sleutelmetadata worden teruggegeven.

{
  "data": {
    "id": "abcdefghijklmno",
    "username": "streamer",
    "display_name": "Streamer",
    "scopes": [
      "activity:read"
    ],
    "key": {
      "prefix": "dl_live_123456789",
      "expires_at": "2026-12-06 12:00:00.000Z"
    }
  }
}

Lees de gezamenlijke feed van DonoLink-donaties en opgeslagen platformevents. Het account wordt uitsluitend uit de API key bepaald.

Onbekende of dubbele parameters leveren HTTP 400 op. Geef geen account-ID, sleutel of PocketBase-filter in de URL mee.

Eventformaat

Elk event heeft een stabiel id met don_ of evt_ als voorvoegsel. Gebruik dit id om dubbele verwerking na een retry te voorkomen.

actor.name is de opgeslagen schermnaam of null. message is tekst of null. occurred_at is de donatiedatum; bij platformevents is alleen de opslagtijd bekend. recorded_at is altijd de opslagtijd en bepaalt de paginering. Alle tijden zijn UTC ISO 8601.

value bevat bij donation het oorspronkelijke bedrag in gehele centen, currency de valuta. refunded_amount_cents bevat voor DonoLink het terugbetaalde bedrag, anders null. Donaties met status paid worden getoond, inclusief geïmporteerde historie met de importbron als platform. Volledig terugbetaalde en betwiste donaties ontbreken. Dit is een activity feed, geen financieel grootboek.

Platformevents zijn beschikbaar voor zover DonoLink ze via een actieve koppeling heeft ontvangen en opgeslagen. Er wordt geen geschiedenis van vóór de koppeling bij het platform opgehaald. Er is geen gegarandeerde bewaartermijn; verwijderde records zijn niet meer opvraagbaar. Testalerts staan niet in deze feed.

Webhooks

Van endpoint naar eerste event

Voeg in Instellingen bij Uitgaande webhooks een publiek HTTPS-adres toe. Kies je gebeurtenissen en bewaar het ondertekeningsgeheim. De API key voor de activity-feed en dit geheim hebben elk hun eigen functie.

1. Publiceer een HTTPS-route op poort 443 met een geldig certificaat. 2. Voeg de URL in Instellingen → Uitgaande webhooks toe en kies gebeurtenissen. 3. Bewaar het volledige whsec_-geheim als omgevingsvariabele op je server. 4. Verstuur een test en controleer de aflevering in het dashboard.

Headers en berichtformaat

Content-Type is application/json. DonoLink-Event-Id is dezelfde unieke ID als body.id. DonoLink-Timestamp is de Unix-tijd in seconden van deze verzendpoging. DonoLink-Attempt begint bij 1. DonoLink-Signature bevat v1= gevolgd door 64 hextekens. Headernamen zijn niet hoofdlettergevoelig; gebruik het volledige signing secret inclusief whsec_.

{
  "id": "evt_example",
  "type": "donation.created",
  "created_at": "2026-09-08T12:00:00.000Z",
  "test": false,
  "data": {
    "id": "donation_record",
    "amount_cents": 500,
    "currency": "eur",
    "donor_name": "Kijker",
    "message": "Hoi",
    "status": "paid"
  }
}

donation.created verschijnt voor een betaalde donatie. donation.refunded bevat het cumulatief terugbetaalde donatiebedrag. donation.chargeback meldt een gewijzigd geschil met de actuele donatiestatus. subscription.created verschijnt na de eerste betaalde maandelijkse bijdrage. Donateurs-e-mailadressen en betaalgegevens worden nooit meegestuurd. test=true herken je als een door de streamer verstuurd testbericht.

created_at is het tijdstip van de gebeurtenis in UTC. Bedragen zijn gehele centen; valuta is eur. data.id is de interne DonoLink-record-ID. Velden kunnen per event ontbreken: ga niet uit van één vast object voor alle soorten. Een subscription_id bij subscription.created is de DonoLink-abonnements-ID, geen Stripe-ID.

Controleer DonoLink-Signature met HMAC-SHA256 over timestamp.event-id.raw-body. Gebruik de originele bodybytes voordat je JSON ontleedt. Controleer ook de DonoLink-Timestamp header, maximaal vijf minuten verschil. Het voorbeeld hieronder geeft alleen geldige, recente handtekeningen door.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(headers, rawBody, secret) {
  const id = headers['donolink-event-id'];
  const timestamp = headers['donolink-timestamp'];
  const signature = headers['donolink-signature'];
  if (typeof id !== 'string' || typeof timestamp !== 'string' ||
      typeof signature !== 'string' || !/^\d+$/.test(timestamp) ||
      !/^v1=[a-f0-9]{64}$/.test(signature)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(timestamp + '.' + id + '.').update(rawBody).digest();
  const received = Buffer.from(signature.slice(3), 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Aflevering, retries en dubbele berichten

Bewaar event.id in je database om herhaalde afleveringen veilig te herkennen. Geef snel een 2xx-respons nadat je het event duurzaam hebt opgeslagen. De volgorde is niet gegarandeerd. Netwerkfouten, HTTP 408/425/429 en 5xx worden maximaal acht keer geprobeerd. Andere 4xx-responsen en redirects stoppen de aflevering. Je kunt mislukte afleveringen bekijken en opnieuw proberen in Instellingen.

De worker controleert de wachtrij ongeveer elke 5 seconden. Een HTTP-poging duurt maximaal 10 seconden. Na een tijdelijke fout volgen maximaal zeven retries, telkens na 1 minuut, 5 minuten, 15 minuten, 1 uur, 3 uur, 6 uur en 12 uur. Deze wachttijden zijn geen aflevergarantie. Een handmatige retry start een nieuwe reeks pogingen met dezelfde event-ID en payload, maar een nieuwe timestamp en handtekening.

Werkend Node.js-ontvangervoorbeeld

Dit voorbeeld controleert de originele body, bewaart unieke events in SQLite en antwoordt pas daarna met 204. Draai Node.js 22.13 of nieuwer, stel DONOLINK_WEBHOOK_SECRET in en plaats de server achter je HTTPS-proxy. Verwerk de inbox met je eigen worker; voer bij test=true geen echte beloning of actie uit.

Problemen oplossen

401/403: controleer je signing secret, klok en raw body; daarna handmatig opnieuw proberen. 404: controleer de route. 3xx: vul de eind-URL in, redirects worden niet gevolgd. 429/5xx: controleer capaciteit en logs; DonoLink probeert opnieuw. dns_failed/timeout/network_error: controleer DNS, TLS en bereikbaarheid. unsafe_target: gebruik een publiek HTTPS-adres; localhost, privé-IP’s en gemengde publieke/interne DNS-antwoorden worden geweigerd. Blijft een test in de wachtrij staan, controleer of de webhookworker draait.

Historie & live feed

Voor een export: gebruik order=asc met vaste since- en until-grenzen. Verwerk data en vraag met next_cursor de volgende pagina op zolang has_more true is. Er is geen limiet op het aantal historische pagina’s, wel een requestlimiet.

Een lege pagina behoudt je bestaande cursor. Zonder eerdere cursor en zonder events is next_cursor null. Cursors bevatten geen API key, maar behandel ze als ondoorzichtige waarden. Na een filterwijziging begin je zonder cursor.

Voor je IRL-app: gebruik order=asc, een vaste since en geen until. Sla de cursor pas op nadat je events hebt verwerkt. Poll ongeveer iedere 5 seconden; bij has_more mag je direct door naar de volgende pagina. Er is in v1 geen WebSocket- of webhookendpoint.

// Node.js: run on your server. Keep the key out of frontend bundles.
const base = new URL('https://donolink.nl/api/v1/activity');
base.searchParams.set('order', 'asc');
base.searchParams.set('limit', '100');
// Persist both this fixed starting point and the returned cursor.
base.searchParams.set('since', '2026-09-07T00:00:00Z');
let cursor = await loadCheckpoint();
for (;;) {
  const url = new URL(base);
  if (cursor) url.searchParams.set('cursor', cursor);
  const response = await fetch(url, {
    headers: { Authorization: 'Bearer ' + process.env.DONOLINK_API_KEY },
    signal: AbortSignal.timeout(15000)
  }).catch(() => null);
  if (!response || response.status === 429 || response.status >= 500) {
    const seconds = Number(response?.headers.get('Retry-After') || 60);
    await new Promise(r => setTimeout(r, seconds * 1000));
    continue;
  }
  if (!response.ok) throw new Error('DonoLink API: ' + response.status);
  const page = await response.json();
  // Implement these storage functions in your app.
  // Process idempotently by event.id, then save the checkpoint.
  for (const event of page.data) await processOnce(event.id, event);
  if (page.pagination.next_cursor) {
    cursor = page.pagination.next_cursor;
    await saveCheckpoint(cursor);
  }
  if (!page.pagination.has_more)
    await new Promise(r => setTimeout(r, 5000));
}

De feed leest de huidige opgeslagen records en is geen onveranderlijke snapshot of gegarandeerde exactly-once eventbus. Wijzigingen in betaalstatus kunnen eerder getoonde records laten verdwijnen. Gebruik idempotente verwerking, retries en indien nodig een overlappende herlezing voor herstel.

Limieten & fouten

Maximaal 120 requests per 60 seconden per account, gedeeld door alle sleutels. Daarnaast geldt 300 requests per 60 seconden per IP-adres. HTTP 429 en 503 bevatten Retry-After: 60. Wacht die tijd en probeer met dezelfde cursor opnieuw.

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid, expired or revoked.",
    "request_id": "request-uuid"
  }
}

Iedere response heeft X-Request-Id; foutresponses bevatten ook error.request_id. Geef dit ID en het tijdstip door bij een supportvraag. Deel nooit je sleutel, Authorization-header of volledige requestlogs. Gebruik GET voor data. HEAD en OPTIONS zijn beschikbaar voor HTTP-controles; schrijfmethodes leveren 405 op.

Veilig integreren

Gebruik HTTPS. Zet sleutels nooit in URL’s, Git, browsercode, localStorage, analytics of logbestanden. API-responses gebruiken Cache-Control: private, no-store. De API biedt geen cross-origin browsertoegang.

In een persoonlijke native app voer je je eigen sleutel in en bewaar je die in Keychain of Android Keystore. Bouw je een app voor anderen, gebruik dan een backend met gescheiden geheimen per gebruiker. Embed nooit een gedeelde sleutel in de appbinary.

De API geeft alleen schermnamen, berichten, eventwaarden en beperkte profielgegevens terug. E-mailadressen, betaalmethodes, Stripe-ID’s, platformtokens en beheerinstellingen worden niet gedeeld. Behandel namen en berichten als persoonsgegevens en bewaar alleen wat je integratie nodig heeft.

Bij een gelekte sleutel: trek hem meteen in onder Instellingen → Developer en maak een nieuwe aan. Ingetrokken en verlopen sleutels, geblokkeerde accounts en verwijderde accounts krijgen geen toegang.

Namen en berichten zijn onbetrouwbare invoer. Render ze als tekst, nooit als HTML of uitvoerbare code. Automatiseer geen betaalacties op basis van deze feed.