Build on your stream.

Quick start

Use the API from your own server or personal app. All endpoints are read-only and use JSON. The base URL is https://donolink.nl/api/v1.

1. Go to Settings → Developer → API keys. Name your integration and choose an expiry date.
2. Copy the key once and store it as DONOLINK_API_KEY in your server secret configuration.
3. Make your first request. Without filters, you receive up to 50 events, newest first.

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

Example response

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

Authentication

Send your key in the Authorization header with every request. A session cookie, query parameter or overlay token does not grant access to this API.

Authorization: Bearer dl_live_YOUR_SECRET_KEY

Choose a validity of 30, 90 or 365 days. You can have up to 10 active keys and create one key per minute. DonoLink stores only a SHA-256 hash; the full key is visible only immediately after creation.

Use a separate key per integration. To rotate, create a new key, update your app, then revoke the old one. A revoked or expired key stops working on the next request.

Every key has the fixed activity:read scope and is bound to your account. There are no write, payment or administration permissions. OAuth for multi-customer apps is not available yet.

Endpoints

Check which streamer your key belongs to and when it expires. Only the public profile, scope and key metadata are returned.

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

Read the combined feed of DonoLink donations and stored platform events. The account is determined exclusively from the API key.

Unknown or repeated parameters return HTTP 400. Do not put an account ID, key or PocketBase filter in the URL.

Event format

Each event has a stable id prefixed with don_ or evt_. Use this id to prevent duplicate processing after a retry.

actor.name is the stored display name or null. message is text or null. occurred_at is the donation date; for platform events only the storage time is known. recorded_at always contains the storage time and determines pagination. All timestamps are UTC ISO 8601.

For donation, value is the original amount in integer cents and currency is the currency. refunded_amount_cents contains the refunded amount for DonoLink, otherwise null. Donations with status paid are shown, including imported history with the import source as platform. Fully refunded and disputed donations are excluded. This is an activity feed, not a financial ledger.

Platform events are available to the extent DonoLink received and stored them through an active connection. History from before the connection is not fetched from the platform. There is no guaranteed retention period; deleted records cannot be retrieved. Test alerts are not included.

Webhooks

From endpoint to first event

Add a public HTTPS endpoint under Settings, Outgoing webhooks. Choose your events and save the signing secret. Your activity API key and this secret serve separate purposes.

1. Publish an HTTPS route on port 443 with a valid certificate. 2. Add its URL in Settings → Outgoing webhooks and choose events. 3. Save the entire whsec_ secret as a server environment variable. 4. Send a test and check its delivery in the dashboard.

Headers and payload

Content-Type is application/json. DonoLink-Event-Id matches body.id. DonoLink-Timestamp is the Unix time in seconds of this delivery attempt. DonoLink-Attempt starts at 1. DonoLink-Signature contains v1= followed by 64 hex characters. Header names are case-insensitive; use the entire signing secret including 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 reports a paid donation. donation.refunded includes the cumulative refunded donation amount. donation.chargeback reports a changed dispute with the current donation status. subscription.created is emitted after the first paid monthly contribution. Donor email addresses and payment credentials are never included. test=true identifies a test sent by the streamer.

created_at is the event time in UTC. Amounts are integer cents; currency is eur. data.id is the internal DonoLink record ID. Fields can be absent depending on event type; do not assume one fixed object for all events. subscription_id in subscription.created is the DonoLink subscription ID, not a Stripe ID.

Verify DonoLink-Signature using HMAC-SHA256 over timestamp.event-id.raw-body. Use the original body bytes before parsing JSON. Also verify the DonoLink-Timestamp header with a maximum five-minute difference. The example below accepts only valid, recent signatures.

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);
}

Delivery, retries and duplicates

Persist event.id in your database to safely recognize repeated deliveries. Return a 2xx response promptly after durably storing the event. Ordering is not guaranteed. Network failures, HTTP 408/425/429 and 5xx responses are attempted up to eight times. Other 4xx responses and redirects end delivery. View failed deliveries and retry them in Settings.

The worker checks the queue roughly every 5 seconds. An HTTP attempt times out after 10 seconds. Temporary failures receive up to seven retries after 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours and 12 hours respectively. These delays are not delivery guarantees. A manual retry starts a new attempt sequence with the same event ID and payload, but a fresh timestamp and signature.

Runnable Node.js receiver

This example verifies the raw body, persists unique events in SQLite and only then returns 204. Run Node.js 22.13 or newer, set DONOLINK_WEBHOOK_SECRET and put the server behind your HTTPS proxy. Process the inbox with your own worker; do not grant real rewards or perform real actions for test=true.

Troubleshooting

401/403: check your signing secret, clock and raw body, then retry manually. 404: verify the route. 3xx: use the final URL; redirects are not followed. 429/5xx: inspect capacity and logs; DonoLink retries. dns_failed/timeout/network_error: check DNS, TLS and connectivity. unsafe_target: use a public HTTPS address; localhost, private IPs and mixed public/private DNS answers are rejected. If a test remains queued, check that the webhook worker is running.

History & live feed

For an export, use order=asc with fixed since and until boundaries. Process data and request the next page using next_cursor while has_more is true. There is no limit on historical page count, but request limits apply.

An empty page preserves your existing cursor. With no previous cursor and no events, next_cursor is null. Cursors contain no API key, but treat them as opaque values. After changing filters, start without a cursor.

For your IRL app, use order=asc, a fixed since and no until. Save the cursor only after processing events. Poll about every 5 seconds; when has_more is true, continue directly to the next page. v1 has no WebSocket or webhook endpoint.

// 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));
}

The feed reads current stored records and is not an immutable snapshot or a guaranteed exactly-once event bus. Payment status changes can remove previously visible records. Use idempotent processing, retries and, when needed, overlapping reads for recovery.

Limits & errors

Maximum 120 requests per 60 seconds per account, shared by all keys. There is also a limit of 300 requests per 60 seconds per IP address. HTTP 429 and 503 include Retry-After: 60. Wait that long and retry with the same cursor.

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

Every response has X-Request-Id; error responses also include error.request_id. Include this ID and the time when contacting support. Never share your key, Authorization header or full request logs. Use GET for data. HEAD and OPTIONS are available for HTTP checks; write methods return 405.

Secure integration

Use HTTPS. Never put keys in URLs, Git, browser code, localStorage, analytics or log files. API responses use Cache-Control: private, no-store. The API does not provide cross-origin browser access.

In a personal native app, enter your own key and store it in Keychain or Android Keystore. For apps serving others, use a backend with isolated secrets per user. Never embed a shared key in the app binary.

The API returns only display names, messages, event values and limited profile details. Email addresses, payment methods, Stripe IDs, platform tokens and administration settings are not shared. Treat names and messages as personal data and store only what your integration needs.

If a key leaks, revoke it immediately under Settings → Developer and create a replacement. Revoked and expired keys, blocked accounts and deleted accounts cannot access the API.

Names and messages are untrusted input. Render them as text, never as HTML or executable code. Do not automate payment actions based on this feed.