Webhook w Bitrix24 (Alaio) to sposób połączenia portalu z usługą zewnętrzną bez pisania aplikacji: webhook przychodzący daje systemowi zewnętrznemu klucz-URL do wywoływania REST API portalu, wychodzący — zmusza Bitrix24, by sam pukał do twojego URL przy zdarzeniu. To najszybszy sposób integracji, ale ma granice, o których pomoc milczy. Omówmy oba typy, tworzenie, ograniczenia i trzeci scenariusz, który najczęściej jest właśnie potrzebny: webhook z procesu biznesowego.

Czym webhook przychodzący różni się od wychodzącego?

Przychodzący to URL postaci https://portal.bitrix24.com/rest/1/klucz/, pod którym usługa zewnętrzna wywołuje metody REST API: utworzyć leada, zaktualizować deala, pobrać listę zadań. Uprawnienia zadaje się przy tworzeniu (tylko CRM, tylko zadania itd.), akcje wykonywane są w imieniu pracownika-właściciela klucza. Wychodzący — odwrotnie: podajesz URL swojego obsługiwacza i zdarzenie (utworzono leada, zaktualizowano deala), a Bitrix24 wysyła tam POST przy każdym zadziałaniu. Połączenie obu typów daje integrację dwustronną: wychodzący zgłasza „pojawił się kontakt", usługa zewnętrzna wzbogaca dane i webhookiem przychodzącym zapisuje je z powrotem.

Gdzie utworzyć webhook i co sprawdzić?

Sekcja „Dla deweloperów" (w starszych menu — „Aplikacje") → „Inne" → „Webhook przychodzący" / „Webhook wychodzący". Dla przychodzącego: wybierz uprawnienia dostępu wedle minimum — klucz z uprawnieniami „CRM + cała reszta" przy wycieku oddaje napastnikowi całą bazę; skopiuj URL z kluczem i przechowuj go jak hasło. Dla wychodzącego: podaj URL obsługiwacza i token aplikacji do weryfikacji autentyczności — obsługiwacz musi sprawdzać token, inaczej każdy, kto pozna adres, będzie mógł wysyłać podrobione zdarzenia. Dostępność webhooków zależy od taryfy: na części taryf potrzebna jest subskrypcja Bitrix24 Market.

Jakie ograniczenia mają webhooki?

Trzy, o które rozbijają się integracje. Limit zapytań: REST API przyjmuje około dwóch zapytań na sekundę na portal, przy przekroczeniu — błąd QUERY_LIMIT_EXCEEDED; operacje masowe pakuje się w wywołania batch. Webhook wychodzący nie powtarza dostarczenia: jeśli twój obsługiwacz był niedostępny przez trzy sekundy, zdarzenie jest stracone — Bitrix24 nie ponawia. A webhook wychodzący niesie minimum danych (ID i typ zdarzenia) — po pola i tak trzeba iść webhookiem przychodzącym do REST API. Dlatego „niezawodna szyna na webhookach wychodzących" to mit: dla zdarzeń krytycznych potrzebne jest dostarczanie z potwierdzeniem i ponawianiem.

Jak wysłać webhook z procesu biznesowego?

Częsty scenariusz, którego nie ma w standardowych akcjach: przy przejściu deala na etap szarpnąć usługę zewnętrzną — system księgowy, magazyn, bota komunikatora. Pokrywają to dwa roboty Roboteki. „Zapytanie HTTP" wysyła GET lub POST z nagłówkami i treścią, zwraca odpowiedź i kod statusu do zmiennych procesu — dla scenariuszy synchronicznych „spytałem i dostałem odpowiedź" (odpowiedź rozbiera robot „Wyciągnij wartość z JSON po ścieżce"). „Niezawodny webhook" — dla scenariusza „dostarczyć obowiązkowo": powtarza wysyłkę przy niedostępności odbiornika i zdarzenie nie ginie, dopóki usługa zewnętrzna się restartuje. Reguła wyboru: potrzebna odpowiedź tu i teraz — zapytanie HTTP; potrzebna gwarancja dostarczenia powiadomienia — niezawodny webhook.

Kto może tworzyć webhooki i czy da się to ograniczyć?

Każdy pracownik, który ma dostęp do sekcji „Dla deweloperów", a nie tylko administratorzy. Moduł REST zostawia dla administratorów jedynie część gotowych szablonów integracji, na przykład te, które dodają widżet do karty CRM. Zwykły webhook przychodzący lub wychodzący pracownik może utworzyć sam i działa on z uprawnieniami tego pracownika. Osobnego przełącznika „webhooki tylko dla administratorów" nie ma. Dlatego administrator powinien co jakiś czas przeglądać listę webhooków (gdzie ją znaleźć, opisuje następna sekcja). Zablokowanie tworzenia i tak nie usuwa głównego ryzyka: webhook utworzony przez pracownika widzi w CRM dokładnie to, co widzi ten pracownik.

Gdzie zobaczyć istniejące webhooki i jak je usunąć?

Otwórz sekcję „Dla deweloperów" i przejdź do listy integracji. Pracownik widzi tylko swoje webhooki, administrator widzi wszystkie i może filtrować je według autora. Klucz (tajną część adresu URL) widzi tylko jego autor: administrator, który otworzy cudzy webhook, zobaczy gwiazdki zamiast kodu. Jeśli jakaś integracja działa, a nikt nie pamięta, kto ją zrobił, szukaj jej na tej liście po autorze i dacie, a nie po adresie URL. Webhook usuwa się z menu wiersza na liście. Od tej chwili system zewnętrzny dostaje błędy autoryzacji, więc najpierw ustal, kto korzysta z klucza. Webhooki byłych pracowników sprawdź osobno; co się z nimi dzieje po odejściu pracownika, opisuje poradnik o odejściu pracownika.

Czy można zrobić webhook tylko do odczytu?

Webhook przychodzący nie ma pola wyboru „tylko odczyt". Uprawnienia wybiera się przy tworzeniu osobno dla każdego modułu (CRM, zadania, użytkownicy i tak dalej), a w obrębie modułu webhook może i czytać, i zapisywać. Ograniczyć go można tylko przez prawa użytkownika, w imieniu którego działa: webhook wysyła każde zapytanie jako jego autor i podlega roli tego autora. Z tego wynika sprawdzony sposób. Utwórz osobnego użytkownika do integracji, nadaj mu w CRM rolę z dostępem tylko do odczytu potrzebnych elementów i utwórz webhook na jego koncie. Jeśli klucz wycieknie, nie da się nim niczego zmienić ani usunąć. Pamiętaj, że taki użytkownik zajmuje jedno miejsce w limicie użytkowników twojego planu. Dodatkowa korzyść: integracja przestaje zależeć od jednego konkretnego menedżera i po jego odejściu wymiana danych dalej działa.

Co dać wykonawcy, który będzie przysyłał nam leady?

Zwykle prosi o „URL albo webhook" i chodzi mu o to samo: adres webhooka przychodzącego, który jego system będzie wywoływał metodą crm.lead.add. Wydaj klucz tylko z modułem CRM, utworzony na koncie użytkownika do integracji z poprzedniej sekcji, a nie na twoim koncie administratora. Ten adres działa jak hasło: każdy, kto go ma, może zapisywać dane w twoim CRM. Gdy kończysz współpracę z wykonawcą, usuń webhook z listy integracji i dostęp natychmiast wygasa. Jeśli wykonawca ma tylko przesyłać zgłoszenia ze strony internetowej, prostszy jest formularz CRM: wtedy klucz do REST API w ogóle nie jest potrzebny.

Robot „Webhook wychodzący": co wpisać w polu „Handler"?

Bitrix24 ma standardowego robota „Webhook wychodzący". Ma on jedno pole, „Handler", w które wpisujesz adres swojej usługi: http lub https, z nazwą domeny. Robot wysyła tam zapytanie z identyfikatorem dokumentu (document_id, na przykład deal DEAL_10) i od razu idzie dalej. Nie czeka na odpowiedź i niczego nie zwraca do procesu. Nie przesyła też pól deala. Potrzebne wartości dopisz do adresu jako parametry: https://example.com/hook?deal={=Document:ID}&sum={=Document:OPPORTUNITY}. Jeszcze jedna osobliwość: jeśli REST nie jest dostępny w twoim planie, robot po cichu nic nie robi, a w logu nie pojawia się żaden błąd. Gdy potrzebujesz nagłówka autoryzacji, treści w JSON albo odpowiedzi usługi w zmiennej procesu, użyj robota „Zapytanie HTTP". Gdy zdarzenie nie może przepaść, użyj robota „Niezawodny webhook": ponawia wysyłkę według harmonogramu, maksymalnie dziesięć razy.

Webhook nie działa: lista kontrolna

Przychodzący zwraca błąd: sprawdź uprawnienia klucza (metoda wymaga zakresu, którego nie ma), aktywność pracownika-właściciela (zwolniony pracownik = martwy klucz) i limit zapytań. Wychodzący nie przychodzi: sprawdź, czy obsługiwacz odpowiada kodem 200 szybko (długą odpowiedź Bitrix24 uznaje za błąd), czy URL jest dostępny z zewnątrz (nie localhost, nie zamknięty firewallem) i czy zdarzenie jest faktycznie tym właściwym — „aktualizacja deala" nie działa na zmianę etapu kanbana zadań. I pamiętaj o braku ponowień: jeśli odbiornik leżał, zdarzenie trzeba odtwarzać ręcznie — albo od początku wysyłać przez niezawodny webhook z procesu.

Podsumowanie

Webhooki to najtańszy sposób integracji z Bitrix24: przychodzący do sterowania portalem z zewnątrz, wychodzący do sygnałów na zewnątrz, a z procesów biznesowych — roboty z zapytaniem HTTP i gwarancją dostarczenia z katalogu Roboteki. Brak potrzebnego scenariusza — opisz zadanie, zrobimy robota bezpłatnie.