↑↓ wybierzEnter otwórzEsc zamknij

    1. Elbuz
    2. API v2: jak podłączyć własny program do danych Elbuz

    Webhooki API v2: jak otrzymywać powiadomienia o zmianach

    11 min czytaniaZaktualizowano

    Elbuz sam wysyła na adres Twojego serwera powiadomienie, gdy zmieniają się klienci, dokumenty albo w „Pulsie” zostaje zaakceptowana propozycja. Nie trzeba co minutę pytać API „co nowego”.

    Kiedy to się przyda:

    • Nowi klienci mają trafiać do Twojego CRM — zdarzenie przychodzi w ciągu minuty od utworzenia.
    • Zatwierdzone zamówienie trzeba przekazać do magazynu — zdarzenie documents.signed dla każdego dokumentu.
    • Twój serwer nie nadąża za strumieniem — zdarzenia przychodzą paczkami do 100, z limitem zapytań na minutę.
    • Serwer był niedostępny — paczka zostanie wysłana ponownie, łącznie do sześciu prób.

    Od czego zacząć: utwórz subskrypcję zapytaniem do API tym kluczem, którym będziesz czytać rekordy.

    Co potrafią webhooki

    Jak zasubskrybować

    Subskrypcję tworzy się zapytaniem API tym kluczem, którym potem będziesz czytać rekordy. Klucz wydaje się w oknie „API i tokeny dostępu” (szczegóły — API v2: klucze); do subskrypcji klucz musi mieć odznaczone „Tylko do odczytu”.

    Karta klucza API v2: w imieniu pracownika, tryb zmian danych, bezpiecznik i nowy klucz
    1W imieniu pracownika
    2Zmiany danych
    3Bezpiecznik: zmian na godzinę
    4Bieżący klucz
    5Tylko do odczytu
    1. W imieniu pracownika — czyje uprawnienia i dane dostaje klucz. Innych pracowników widzi tylko ten, kto ma dostęp do okna użytkowników.
    2. Zmiany danych — „Pytaj” (każda zmiana czeka w „Pulsie”) albo „Wykonuj samodzielnie”. Przełączyć może tylko „Zarząd”.
    3. Bezpiecznik — po tylu wykonanych zmianach w ciągu godziny klucz sam wraca do trybu „Pytaj”.
    4. Nowy klucz widać tylko raz: skopiuj go przyciskiem „Kopiuj”, zanim zamkniesz okno.
    5. Tylko do odczytu — zaznaczone w nowym kluczu; odznacz, jeśli klucz ma coś zmieniać.

    Konto na app.elbuz.com wysyła na https://app.elbuz.com/api/v2/webhooks?user_domain=<numer konta> — tak samo jak wszystkie zapytania API.

    curl -s -X POST "https://<twoja-domena>/api/v2/webhooks" \
      -H "Authorization: Bearer elbz_…" -H "Content-Type: application/json" \
      -H "Idempotency-Key: wh-crm-sync-1" \
      -d '{"url":"https://example.com/elbuz-hook",
           "events":["contractors.created","contractors.deleted","documents.updated"],
           "description":"CRM sync","batch":1,"rate_per_min":60}'

    Odpowiedź 201 (konto demo, 14.10.2026):

    {"data":{"secret":"whsec_biVB0fz/Dm5U0yfY59idgl5lpaXngK7Vey3ngKCZzpY=",
     "webhook_id":9,"url":"https://example.com/elbuz-hook",
     "events":["contractors.created","contractors.deleted","documents.updated"],
     "status":"active","description":"CRM sync","batch":1,"rate_per_min":60, …}}

    Sekret whsec_… jest pokazywany tylko w tej odpowiedzi. W bazie przechowywany jest w postaci zaszyfrowanej, GET /api/v2/webhooks/9 go nie zwraca, a ponowienie zapytania z tym samym Idempotency-Key zwróci „*** shown once ***”. Zgubiony sekret? Usuń subskrypcję i utwórz nową.

    PoleCo ustawia
    urltylko https na standardowym porcie, bez loginu i hasła w adresie; wszystkie adresy IP hosta muszą być publiczne
    eventsco najmniej jedno zdarzenie z listy poniżej
    batch1 (domyślnie) — tablica do 100 zdarzeń w jednym zapytaniu; 0 — jedno zdarzenie na zapytanie
    rate_per_minile zapytań na minutę Elbuz wyśle najwyżej, od 1 do 600, domyślnie 60
    statusactive lub off; active zdejmuje też stan error
    descriptionnotatka, do 255 znaków

    Zmiana — PATCH /api/v2/webhooks/{id}, usunięcie — DELETE (odpowiedź 204, dziennik dostarczeń zostaje). Subskrypcje widzi i zmienia tylko klucz, który je utworzył: inny klucz tego samego konta dostanie 404. Subskrypcje nie tworzą propozycji w „Pulsie” — w żadnym trybie klucza.

    Adres jest sprawdzany przy tworzeniu, przy zmianie i przed każdą wysyłką. Odmowy przychodzą z wyjaśnieniem: url: https URL required, url: private or reserved ip, url: port not allowed. Przekierowań (3xx) Elbuz nie wykonuje — taka odpowiedź liczy się jako błąd dostarczenia.

    Jakie zdarzenia można subskrybować

    ZdarzenieKiedy
    contractors.created, contractors.updated, contractors.deletedklienta lub dostawcę utworzono, zmieniono, przeniesiono do kosza — w oknie, importem, starym API lub API v2
    documents.created, documents.updated, documents.deleted, documents.signeddokument (zamówienie, fakturę, umowę) utworzono, zmieniono, przeniesiono do kosza, zatwierdzono. documents.updated przychodzi też wtedy, gdy zamówienie zmienił import: tunel, marketplace’y aktualizujące zamówienia (lista), POST /orders/sync. Zamówienie przyszło bez zmian — zdarzenia nie ma
    documents.payment_overdueminął termin płatności dokumentu
    pulse.approvedw „Pulsie” zaakceptowano propozycję

    Subskrybować można tylko zdarzenia zasobów, które widzi właściciel klucza: brak dostępu do okna klientów — contractors.* zwróci 422 „events: no access to contractors”. Zdarzeń o produktach na razie nie ma: zmiany katalogu pobieraj listą GET /api/v2/products?filter[updated_since]=….

    Co przychodzi w zapytaniu

    Przy batch=1 treść to tablica do 100 zdarzeń, przy batch=0 — jeden taki obiekt. Przykład zapytania (wartości identyfikatorów i podpisu są umowne):

    POST /elbuz-hook
    Content-Type: application/json
    User-Agent: Elbuz-Webhooks/1
    webhook-id: msg_3db9ec1f3f81b1fa1bf46510
    webhook-timestamp: 1791974700
    webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
    
    [{"id":"evt_96788537a68c0722d7b6fa82","type":"contractors.updated","timestamp":"2026-10-14T10:45:00Z",
      "data":{"id":19277,"resource":"contractors"}},
     {"id":"evt_1f0c2a9e44d7b8a5c3e6f701","type":"documents.signed","timestamp":"2026-10-14T10:45:02Z",
      "data":{"id":5120,"resource":"documents"}}]

    Zdarzenie zawiera tylko id rekordu. Samych danych w treści nie ma: odczytaj rekord przez GET /api/v2/{resource}/{id} swoim kluczem. Dzięki temu zawsze dostajesz świeży stan i tylko te pola, na które klucz ma zgodę. timestamp — czas zdarzenia w UTC.

    Działanie zbiorcze — jedno zdarzenie

    Jeśli w jednym działaniu zmienił się więcej niż jeden rekord tego samego rodzaju — usunięto zaznaczone w tabeli, zmieniono pole w setce dokumentów, przeszedł import — przychodzi nie setka zdarzeń, tylko jedno {resource}.bulk_{action}:

    {"id":"evt_…","type":"contractors.bulk_deleted","timestamp":"2026-10-14T10:44:58Z",
     "data":{"resource":"contractors","action":"deleted","count":50,
             "ids":[19227,19228,19229, …],"truncated":false,"operation_id":"op_3514f5e4c0df634e"}}

    W ids — do 1000 id; jeśli rekordów jest więcej, truncated: true, a dla utworzonych i zmienionych jest jeszcze list_url — lista zmian z ostatniej godziny, którą doczytuje się kursorem.

    bulk_* nie subskrybuje się osobno: subskrypcja contractors.deleted dostaje też contractors.bulk_deleted. Wyjątek — documents.payment_overdue: zawsze osobne zdarzenie na dokument i nie częściej niż raz na 30 dni dla tego samego dokumentu.

    Kilka zmian jednego rekordu

    Zdarzenie updated czeka 60 sekund przed wysłaniem. Jeśli w tym czasie ten sam rekord zmieniono jeszcze raz, nowe zdarzenie nie jest dodawane — dostaniesz jedno i odczytasz już stan końcowy. Zdarzenia created, deleted, signed nie czekają.

    Kiedy przychodzi

    W chwili działania nic nie jest wysyłane: zdarzenia zbierają się do końca działania (zapytania, importu), potem trafiają do kolejki subskrypcji, a wysyła je zadanie w tle. Licz się z opóźnieniem do minuty, dla updated — plus 60 sekund scalania.

    Paczki idą po kolei — w jednej subskrypcji nigdy nie lecą dwa zapytania naraz. Ale updated po 60 sekundach scalania może przyjść później niż zdarzenie, które nastąpiło po nim — np. po deleted tego samego rekordu. Opieraj się na stanie z GET, a nie na kolejności zdarzeń.

    Jak sprawdzić podpis

    Format — Standard Webhooks. Podpis to HMAC-SHA256 z ciągu webhook-id + "." + webhook-timestamp + "." + surowa treść; klucz — zdekodowana część base64 sekretu po whsec_; wynik w base64 z prefiksem v1,. Podpisywana jest treść bajt w bajt: nie parsuj przed sprawdzeniem. Odrzucaj zapytania, w których webhook-timestamp różni się od bieżącego czasu o więcej niż 5 minut.

    PHP

    $secret = 'whsec_…';
    $id   = $_SERVER['HTTP_WEBHOOK_ID'];
    $ts   = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'];
    $body = file_get_contents('php://input');
    
    $key = base64_decode(substr($secret, 6));
    $expected = 'v1,' . base64_encode(hash_hmac('sha256', $id . '.' . $ts . '.' . $body, $key, true));
    $valid = abs(time() - (int)$ts) <= 300
          && in_array(true, array_map(fn($s) => hash_equals($expected, $s),
                                      explode(' ', $_SERVER['HTTP_WEBHOOK_SIGNATURE'])), true);
    if (!$valid) { http_response_code(401); exit; }

    Node.js (Express)

    const crypto = require('crypto');
    app.post('/elbuz-hook', express.raw({ type: 'application/json' }), (req, res) => {
      const key = Buffer.from(process.env.ELBUZ_WHSEC.slice(6), 'base64');
      const id = req.get('webhook-id'), ts = req.get('webhook-timestamp');
      const expected = 'v1,' + crypto.createHmac('sha256', key)
        .update(id + '.' + ts + '.' + req.body.toString('utf8')).digest('base64');
      const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
      const ok = req.get('webhook-signature').split(' ').some(s =>
        s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
      if (!fresh || !ok) return res.sendStatus(401);
      res.sendStatus(200);
    });

    Python

    import base64, hashlib, hmac, time
    
    def valid(secret, headers, raw_body: bytes) -> bool:
        key = base64.b64decode(secret[6:])
        msg = f"{headers['webhook-id']}.{headers['webhook-timestamp']}.".encode() + raw_body
        expected = "v1," + base64.b64encode(hmac.new(key, msg, hashlib.sha256).digest()).decode()
        fresh = abs(time.time() - int(headers['webhook-timestamp'])) <= 300
        return fresh and any(hmac.compare_digest(expected, s) for s in headers['webhook-signature'].split())

    Wszystkie trzy przykłady sprawdzono na podpisie obliczonym tak samo, jak oblicza go Elbuz.

    Co odpowiadać i jak Elbuz ponawia

    Co Elbuz robi z paczką w zależności od odpowiedzi Twojego serwera
    2xxjest Retry-Afterinny kod lub przekroczonyczasnietaktakniePaczka do 100 zdarzeńPOST na Twój adresOdpowiedź serweraDostarczono, następna paczkaPauza subskrypcji na podany czas,próba się nie liczyTo już 6 prób?Ponowienie tej samej paczki po 1min, 5 min, 30 min, 2 godz., 6 godz.Paczka failedTrzecia failed z rzędu?Subskrypcja w stanie error,zdarzenia się nie gromadzą
    • Початок або кінець
    • Дія або результат
    • Розвилка: далі шлях залежить від відповіді
    • Dowolny kod 2xx — paczka dostarczona. Odpowiadaj szybko: Elbuz czeka 15 sekund (na połączenie — 5). Ciężkie przetwarzanie przenieś do własnej kolejki.
    • Inny kod, przekroczenie czasu, zerwane połączenie — paczka zostanie wysłana ponownie w całości: ten sam webhook-id, ta sama treść, nowy webhook-timestamp i podpis. Łącznie 6 prób: od razu, po 1 minucie, 5 minutach, 30 minutach, 2 godzinach, 6 godzinach.
    • Nagłówek Retry-After (zwykle z 429) — subskrypcja wstrzymuje się na podaną liczbę sekund, maksymalnie na dobę. Taka odpowiedź nie liczy się jako próba: dopóki odpowiadasz z Retry-After, paczka będzie wysyłana ponownie bez limitu, a sześć prób liczy się tylko dla błędów bez tego nagłówka.
    • Dopóki paczka czeka na ponowienie, nowe zdarzenia subskrypcji czekają za nią — kolejność nie jest naruszana.
    • Sześć prób wyczerpanych — paczka i jej zdarzenia dostają status failed i nie są już wysyłane. Po trzech takich paczkach z rzędu subskrypcja przechodzi w stan error.

    Subskrypcja w stanie off lub error nie gromadzi zdarzeń: zmiany, które zaszły, gdy nie działała, już nie przyjdą. Po przywróceniu (PATCH {"status":"active"}) doczytaj pominięte listą ?filter[updated_since]= od czasu ostatniego udanego dostarczenia.

    Przetwarzanie bez duplikatów

    Paczka może przyjść dwa razy: Twój serwer ją przetworzył, ale odpowiedź nie dotarła. Zapamiętuj id każdego zdarzenia (evt_…) i pomijaj już przetworzone. Właśnie id zdarzenia, a nie webhook-id: webhook-id należy do paczki.

    Dziennik dostarczeń

    GET /api/v2/webhook_deliveries?filter[webhook_id]=9 — ostatnie 200 paczek subskrypcji, najnowsze na górze:

    {"delivery_id":51,"msg_id":"msg_3db9ec1f3f81b1fa1bf46510","types":"contractors.updated",
     "events_count":"50","status":"sent","attempts":"1","response_code":"200","error":"",
     "next_try":null,"date_try":"…","date_sent":"…"}

    status: queued — w przygotowaniu, retry — czeka na ponowienie do next_try, sent — dostarczono, failed — próby wyczerpane. Dziennik i zdarzenia są przechowywane 30 dni.

    Scenariusze

    Nowi klienci — do Twojego CRM

    Subskrypcja contractors.created. Na każde zdarzenie — GET /api/v2/contractors/{id}; na contractors.bulk_created po imporcie — GET /api/v2/contractors?filter[contractor_id][gte]=… albo przejście po ids.

    Zatwierdzone zamówienie — do magazynu

    Subskrypcja documents.signed, batch=0, jeśli Twój magazyn przyjmuje zamówienia pojedynczo. Pozycje — GET /api/v2/document_items?filter[document_id]={id}.

    Wolny odbiorca

    Serwer wytrzymuje 10 zapytań na minutę: rate_per_min=10 i batch=1 — do 1000 zdarzeń na minutę paczkami po 100. W szczycie odpowiadaj 429 z Retry-After: 60.

    Co zrobić, gdy zdarzenia nie przychodzą

    Najczęstsze problemy
    Co widziszDlaczego tak jestCo zrobić
    422 „url: https URL required”adres na httptylko https (subskrypcja)
    422 „url: private or reserved ip”host wskazuje na adres wewnętrznyadres publiczny lub tunel
    422 „events: unknown event …”zdarzenia nie ma na liściezob. zdarzenia; bulk_* nie subskrybuje się osobno
    Podpis się nie zgadzapodpisywana jest przekształcona treść albo klucz nie został zdekodowany z base64sprawdzaj surowe bajty treści (sprawdzanie podpisu)
    Te same zdarzenia przyszły dwa razyponowienie paczki po błędzie lub przekroczeniu czasupomijaj przetworzone evt_…
    Zdarzenia przestały przychodzić, status: errortrzy paczki z rzędu nie zostały dostarczonePATCH {"status":"active"} i doczytaj pominięte

    Najczęstsze pytania

    Skąd wziąć sekret podpisu webhooka?

    Tylko z odpowiedzi na utworzenie subskrypcji, pole secret (whsec_…). Później nie da się go wyświetlić; zgubiony — utwórz nową subskrypcję.

    Dlaczego przyszło jedno zdarzenie zamiast setki?

    Działanie zbiorcze (usunięcie zaznaczonych, edycja zbiorcza, import) daje jedno zdarzenie {resource}.bulk_{action} z count i ids do 1000.

    Ile razy Elbuz ponawia dostarczenie?

    Sześć prób: od razu, po 1 min, 5 min, 30 min, 2 godz. i 6 godz. Odpowiedź z Retry-After robi pauzę do doby i nie liczy się jako próba.

    Dlaczego w zdarzeniu nie ma danych klienta?

    Zdarzenie zawiera tylko id. Rekordy odczytuje się przez GET /api/v2/{resource}/{id} — ze świeżym stanem i uprawnieniami klucza.

    Czy są webhooki o zmianie produktów?

    Nie. Dla katalogu — lista GET /api/v2/products?filter[updated_since]=… z przeglądaniem kursorem.

    Jak przetestować webhooki na własnym komputerze?

    Tylko przez publiczny tunel https: adresy na http i wewnętrzne Elbuz odrzuca (wymagania dotyczące adresu).

    Gdzie to jest i kto ma dostęp

    W oknach programu subskrypcji nie ma: tworzy się je i zmienia zapytaniami .

    Klucz
    klucz API v2 bez „Tylko do odczytu” (jak wydać)
    Uprawnienia
    zdarzenia — tylko o zasobach, które widzi właściciel klucza
    Przygotuj
    adres https:// na Twoim serwerze, dostępny z internetu

    Powiązane tematy

    Czy ten artykuł był pomocny?

    Brakuje funkcji? Napisz do nas.

    Dodamy ją za darmo, jeśli przyda się też innym.

    Jeśli potrzebujesz jej tylko ty — umówimy się osobno.

    Spis treści

    Zaproponuj usprawnienie

    Wypróbuj Elbuz za darmo