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.signeddla 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
- Powiadamiać o klientach i dokumentach — utworzenie, zmiana, przeniesienie do kosza, zatwierdzenie, przeterminowana płatność, zaakceptowana propozycja w „Pulsie”.
- Łączyć działanie zbiorcze w jedno zdarzenie — zamiast setki zdarzeń przychodzi jedno z listą id.
- Scalać kilka zmian jednego rekordu — czytasz już stan końcowy.
- Podpisywać każde zapytanie zgodnie ze standardem Standard Webhooks.
- Ponawiać dostarczenie i robić pauzę, gdy Twój serwer o to prosi.
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”.
1
W imieniu pracownika2
Zmiany danych3
Bezpiecznik: zmian na godzinę4
Bieżący klucz5
Tylko do odczytu- W imieniu pracownika — czyje uprawnienia i dane dostaje klucz. Innych pracowników widzi tylko ten, kto ma dostęp do okna użytkowników.
- Zmiany danych — „Pytaj” (każda zmiana czeka w „Pulsie”) albo „Wykonuj samodzielnie”. Przełączyć może tylko „Zarząd”.
- Bezpiecznik — po tylu wykonanych zmianach w ciągu godziny klucz sam wraca do trybu „Pytaj”.
- Nowy klucz widać tylko raz: skopiuj go przyciskiem „Kopiuj”, zanim zamkniesz okno.
- 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ą.
| Pole | Co ustawia |
|---|---|
url | tylko https na standardowym porcie, bez loginu i hasła w adresie; wszystkie adresy IP hosta muszą być publiczne |
events | co najmniej jedno zdarzenie z listy poniżej |
batch | 1 (domyślnie) — tablica do 100 zdarzeń w jednym zapytaniu; 0 — jedno zdarzenie na zapytanie |
rate_per_min | ile zapytań na minutę Elbuz wyśle najwyżej, od 1 do 600, domyślnie 60 |
status | active lub off; active zdejmuje też stan error |
description | notatka, 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ć
| Zdarzenie | Kiedy |
|---|---|
contractors.created, contractors.updated, contractors.deleted | klienta lub dostawcę utworzono, zmieniono, przeniesiono do kosza — w oknie, importem, starym API lub API v2 |
documents.created, documents.updated, documents.deleted, documents.signed | dokument (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_overdue | minął termin płatności dokumentu |
pulse.approved | w „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
- Початок або кінець
- Дія або результат
- Розвилка: далі шлях залежить від відповіді
- 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ść, nowywebhook-timestampi 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 zRetry-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
failedi nie są już wysyłane. Po trzech takich paczkach z rzędu subskrypcja przechodzi w stanerror.
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ą
| Co widzisz | Dlaczego tak jest | Co zrobić |
|---|---|---|
| 422 „url: https URL required” | adres na http | tylko https (subskrypcja) |
| 422 „url: private or reserved ip” | host wskazuje na adres wewnętrzny | adres publiczny lub tunel |
| 422 „events: unknown event …” | zdarzenia nie ma na liście | zob. zdarzenia; bulk_* nie subskrybuje się osobno |
| Podpis się nie zgadza | podpisywana jest przekształcona treść albo klucz nie został zdekodowany z base64 | sprawdzaj surowe bajty treści (sprawdzanie podpisu) |
| Te same zdarzenia przyszły dwa razy | ponowienie paczki po błędzie lub przekroczeniu czasu | pomijaj przetworzone evt_… |
Zdarzenia przestały przychodzić, status: error | trzy paczki z rzędu nie zostały dostarczone | PATCH {"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
- Jeśli trzeba odczytać rekord ze zdarzenia — API v2: klucz, listy, zmiany.
- Jeśli zmiany katalogu trzeba pobierać regularnie — listy z filtrem po dacie zmiany.
- Jeśli dane ma analizować Claude lub ChatGPT — podłącz asystenta AI przez MCP.
