Webhook w Bitrix24 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.ru/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.

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.