API HiLobby v1

Szybki start

Wystarczą trzy kroki:

1. W panelu otwórz zakładkę „API i webhooki” i utwórz klucz z potrzebnymi uprawnieniami.
2. Skopiuj klucz (pokazujemy go tylko raz) i zapisz po stronie serwera.
3. Wyślij zapytanie z nagłówkiem Authorization. Odpowiedź /v1 pokazuje uprawnienia klucza i limity.

curl -H "Authorization: Bearer lp_live_..." https://api.hilobby.com/v1

Adres bazowy: https://api.hilobby.com/v1 · OpenAPI 3.1 (JSON)

Uwierzytelnianie

Każde zapytanie (poza specyfikacją OpenAPI) wymaga klucza w nagłówku Authorization (Bearer) albo X-Api-Key.

Authorization: Bearer lp_live_0123456789abcdef0123456789abcdef01234567
X-Api-Key: lp_live_0123456789abcdef0123456789abcdef01234567

• Klucze zaczynają się od lp_live_. Przechowujemy tylko ich skrót, więc zgubionego klucza nie da się odzyskać: wymień sekret albo utwórz nowy.
• Nie używaj klucza w kodzie strony ani aplikacji mobilnej. API jest przeznaczone do wywołań z serwera.
• Klucz możesz ograniczyć do adresów IP (pojedyncze adresy lub zakresy CIDR) i ustawić datę wygaśnięcia.
• Gdy plan PRO+ wygaśnie, klucze przestają działać (błąd plan_required) i wracają po przedłużeniu planu.

Uprawnienia

Każda kategoria ma poziom odczytu (:read) i, gdzie to ma sens, zapisu (:write). Zapis obejmuje odczyt.

Dawaj kluczom tylko potrzebne uprawnienia. Na przykład nakładka na stream potrzebuje zwykle donations:read i live:read.

Limity

• Do 1000 zapytań na godzinę na klucz (ustawienie planu PRO+).
• Dodatkowo krótkotrwały limit chwilowy chroni przed nagłymi seriami zapytań.
• Do 10 kluczy i 5 webhooków na konto.
• Każda odpowiedź ma nagłówki X-RateLimit-*. Po przekroczeniu dostaniesz kod 429 i nagłówek Retry-After.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1792040400
Retry-After: 42

Format odpowiedzi

Udana odpowiedź ma pole data, a listy także next. Błąd ma pole error z kodem i opisem.

{"ok": true, "data": { ... }, "next": 1234}
{"ok": false, "error": {"code": "insufficient_scope", "message": "...", "required_scope": "donations:read"}}

• Kwoty są podawane w złotych (amount) i w groszach (amount_minor).
• Daty są w UTC w formacie ISO 8601, np. 2026-10-15T18:42:07Z.
• Każda odpowiedź ma nagłówek X-Request-Id. Podaj go, gdy zgłaszasz problem.

Kody błędów

Stronicowanie

Listy zwracają najnowsze elementy jako pierwsze. Parametr limit (1-100, domyślnie 25) ustala rozmiar strony, a next z odpowiedzi przekazujesz jako after, aby pobrać kolejną stronę. Gdy next jest null, to koniec listy.

GET /v1/donations?limit=50
GET /v1/donations?limit=50&after=1234

Idempotencja

Zapytania zmieniające dane (POST, PATCH, DELETE) mogą mieć nagłówek Idempotency-Key (do 100 znaków). Powtórzenie zapytania z tym samym kluczem w ciągu 24 godzin zwraca zapisaną odpowiedź (nagłówek Idempotent-Replayed: true) zamiast wykonywać operację drugi raz. Przydaje się przy ponawianiu po błędzie sieci.

curl -X POST -H "Authorization: Bearer lp_live_..." -H "Idempotency-Key: 6f1c2a" \
  -H "Content-Type: application/json" -d '{"title":"Nowy film","url":"https://youtu.be/xyz"}' \
  https://api.hilobby.com/v1/links

Endpointy

Ścieżki są względne wobec /v1 (hosty: api.domena). Treść zapytań wysyłaj jako JSON (Content-Type: application/json). Gwiazdka oznacza pole wymagane.

panel.api_cat_

Profil

Linki

Statystyki

Wsparcia

Wiadomości

Status LIVE

Webhooki

Zmiany zapisane przez API są widoczne w panelu po odświeżeniu strony. Jeśli masz otwarty panel, odśwież go przed edycją, żeby nie nadpisać zmian z API.

Webhooki

Webhook wysyła zdarzenie na Twój adres https zaraz po tym, jak coś się wydarzy. Webhooki dodasz w panelu albo przez API. Zdarzenie zasubskrybujesz przez API tylko wtedy, gdy klucz ma odczyt danej kategorii.

Przykładowe zapytanie:

POST /twoj-adres HTTP/1.1
Content-Type: application/json
User-Agent: HiLobby-Webhooks/1.0
X-HiLobby-Event: donation.received
X-HiLobby-Delivery: evt_3f9a1c0b7d2e4a6f8b1c
X-HiLobby-Timestamp: 1792003327
X-HiLobby-Signature: t=1792003327,v1=5f2b...e91a

{
    "id": "evt_3f9a1c0b7d2e4a6f8b1c",
    "type": "donation.received",
    "created_at": "2026-10-15T18:42:07Z",
    "api_version": "1.0",
    "data": {
        "id": 1234,
        "amount": 25,
        "amount_minor": 2500,
        "currency": "PLN",
        "nick": "Kuba",
        "message": "Pozdrawiam!",
        "email": null,
        "status": "approved",
        "reject_reason": null,
        "provider": "BLIK / przelew",
        "thanked": false,
        "created_at": "2026-10-15T18:41:50Z",
        "paid_at": "2026-10-15T18:42:07Z"
    }
}

• Odpowiedz kodem 2xx w ciągu 8 sekund. Ciężką pracę wykonaj później (kolejka), żeby nie przekroczyć czasu.
• Nieudane dostawy ponawiamy po: 1 min, 5 min, 30 min, 2 h, 6 h, 12 h. Potem dostawa ma status „failed”, a ponowisz ją ręcznie w panelu lub przez API.
• Po 15 nieudanych zdarzeniach z rzędu webhook jest wyłączany, a my wysyłamy Ci e-mail.
• Zdarzenie może przyjść więcej niż raz albo w innej kolejności. Pole id jest unikalne, więc użyj go do pomijania duplikatów.
• Wysyłamy tylko na publiczne adresy https, bez przekierowań.
• Przestarzałe nagłówki: nagłówki ze starej marki (sprzed zmiany na X-HiLobby-*) zostały usunięte - każde zdarzenie jest teraz podpisane wyłącznie nagłówkami X-HiLobby-*.

Weryfikacja podpisu

Nagłówek X-HiLobby-Signature ma postać t=<czas unix>,v1=<hex>. Policz HMAC SHA-256 z tekstu t + "." + treść sekretem webhooka i porównaj z v1 w czasie stałym. Odrzucaj zdarzenia starsze niż 5 minut.

Node.js

const crypto = require('crypto');

// rawBody: tresc zadania jako tekst (przed JSON.parse)
function verify(rawBody, header, secret) {
  const p = Object.fromEntries(header.split(',').map(x => x.split('=')));
  const mac = crypto.createHmac('sha256', secret).update(p.t + '.' + rawBody).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(p.t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(p.v1));
}

PHP

<?php
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_HILOBBY_SIGNATURE'] ?? ''), $p);
$mac = hash_hmac('sha256', ($p['t'] ?? '') . '.' . $raw, getenv('HILOBBY_WEBHOOK_SECRET'));
if (!hash_equals($mac, $p['v1'] ?? '') || abs(time() - (int) ($p['t'] ?? 0)) > 300) {
    http_response_code(400);
    exit;
}
$event = json_decode($raw, true);
// ... obsluga $event['type'] i $event['data']
http_response_code(200);

Python

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    p = dict(x.split('=', 1) for x in header.split(','))
    mac = hmac.new(secret.encode(), (p['t'] + '.').encode() + raw_body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(p['t'])) < 300 and hmac.compare_digest(mac, p['v1'])

Przykłady

Ostatnie zaakceptowane wsparcia

curl -H "Authorization: Bearer $LP_KEY" "https://api.hilobby.com/v1/donations?status=approved&limit=10"

Podsumowanie wsparć (np. do nakładki)

curl -H "Authorization: Bearer $LP_KEY" https://api.hilobby.com/v1/donations/summary

Włączenie statusu LIVE z własnego skryptu

curl -X POST -H "Authorization: Bearer $LP_KEY" -H "Content-Type: application/json" \
  -d '{"live": true, "platform": "twitch", "title": "Granie z widzami"}' https://api.hilobby.com/v1/live

Ukrycie linku

curl -X PATCH -H "Authorization: Bearer $LP_KEY" -H "Content-Type: application/json" \
  -d '{"enabled": false}' https://api.hilobby.com/v1/links/a1b2c3d4e5

Dodanie webhooka

curl -X POST -H "Authorization: Bearer $LP_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/hilobby", "events": ["donation.received", "order.paid"]}' \
  https://api.hilobby.com/v1/webhooks

Wersje i zmiany

Obecna wersja: 1.0. Nowe pola i endpointy dodajemy bez zmiany wersji, więc ignoruj nieznane pola. Zmiany niekompatybilne trafią do nowej ścieżki (np. /api/v2), a o wygaszeniu starej wersji uprzedzimy wcześniej.