Webhooki

Webhook to automatyczne powiadomienie, które panel wysyła do innego systemu po zmianie danych, np. ceny jednostki. Dzięki temu strona internetowa albo system do obsługi klientów (CRM) od razu dostaje aktualne dane i nie trzeba ich przepisywać ręcznie. Odbiór powiadomień trzeba przygotować w systemie odbiorcy, dlatego webhook zakłada się zwykle razem z programistą, który tworzy integrację.

Webhookami zarządzają osoby z rolą Właściciel lub Administrator. Dostęp można też nadać roli niestandardowej z uprawnieniami do webhooków. Role niestandardowe opisuje poradnik Role własne i zakres dostępu.

Otwórz webhooki

Lista webhookówKopiuj link do sekcji

Webhooki są w UstawieniaWebhooki, w grupie Integracje. Lista pokazuje przy każdym webhooku nazwę, zakres, adres w kolumnie Adres URL, liczbę zdarzeń i przełącznik Aktywny. Przyciski nad listą zawężają ją do jednego zakresu, np. Cała organizacja.

Tworzenie webhookaKopiuj link do sekcji

1. Na liście webhooków kliknij Dodaj webhook.
2. W polu Nazwa wpisz nazwę, która pozwoli rozpoznać webhook na liście, np. System CRM.
3. Opcjonalnie w polu Opis wpisz, do czego służy webhook i kto za niego odpowiada.
4. W polu Adres URL wpisz podany przez programistę adres, na który panel ma wysyłać powiadomienia. Adres musi zaczynać się od https://.
5. W polu Zakres wybierz, których danych dotyczą powiadomienia (tabela niżej).
6. W polu Zdarzenia zaznacz co najmniej jedno zdarzenie, np. Zmieniono dane jednostki.
7. W polu Ważność sekretu zostaw 90 dni (zalecane) albo wybierz inny okres.
8. Kliknij Utwórz webhook.

Zdarzenia są podzielone na grupy Deweloperzy, Inwestycje, Jednostki i Biura sprzedaży. Każda grupa obejmuje dodanie, zmianę i usunięcie, a grupa Jednostki także zdarzenie Zmieniono historię cen. Lista dostępnych zdarzeń zależy od zakresu, np. webhook dla jednej inwestycji nie dostaje powiadomień o dodaniu inwestycji.

Jeśli serwer odbiorcy wymaga dodatkowych nagłówków, np. własnego klucza, programista poda ich nazwy i wartości. Dodaje się je w sekcji Nagłówki przyciskiem Dodaj nagłówek. Można dodać najwyżej 20 nagłówków. Nazwa nagłówka może mieć do 64 znaków i zawierać tylko litery bez polskich znaków, cyfry i łączniki. Nazwy Host, Content-Type, Content-Length i User-Agent oraz nazwy zaczynające się od pdd- są zastrzeżone i panel nie pozwoli ich zapisać.

Sekret webhookaKopiuj link do sekcji

Po utworzeniu webhooka panel pokaże okno Sekret webhooka. Sekret to hasło, którym panel podpisuje każde powiadomienie. Dzięki niemu system odbiorcy może sprawdzić, czy powiadomienie pochodzi z panelu.

1. Kliknij Kopiuj. Sekret trafi do schowka, ale na ekranie pozostanie ukryty.
2. Przekaż sekret programiście bezpiecznym kanałem, np. za pomocą firmowego menedżera haseł, a nie zwykłym e-mailem ani komunikatorem.
3. Kliknij Zamknij.

Strona webhookaKopiuj link do sekcji

Kliknięcie webhooka na liście otwiera jego stronę. Nad formularzem widać status webhooka, pole Ważność sekretu z liczbą dni do wygaśnięcia i przyciski Wyślij test oraz Wygeneruj nowy sekret. Strona ma dwie zakładki: Ustawienia z tymi samymi polami co formularz tworzenia i Dziennik dostaw. Zmiany w konfiguracji zapisuje przycisk Zapisz zmiany.

Test webhookaKopiuj link do sekcji

Przycisk Wyślij test wysyła na adres webhooka zdarzenie testowe, podpisane tak jak zwykłe powiadomienia. Panel pokaże komunikat „Zdarzenie testowe zostało przekazane do wysyłki.”, a wynik pojawi się w zakładce Dziennik dostaw. Wyłączony webhook nie wysyła zdarzenia testowego.

Dziennik dostawKopiuj link do sekcji

Zakładka Dziennik dostaw pokazuje każdą próbę dostarczenia powiadomienia. Kolumny podają zdarzenie, status, kod odpowiedzi serwera (Kod odpowiedzi), czas odpowiedzi i godzinę wysłania. Filtr Status zawęża listę do jednego statusu.

Jeśli serwer jest chwilowo niedostępny, przeciążony albo nie odpowiada, system automatycznie ponawia wysyłkę w coraz dłuższych odstępach, łącznie do 9 prób w ciągu około trzech dni. Gdy serwer odrzuci powiadomienie, np. z powodu złego adresu, system nie ponawia wysyłki, bo ponowna próba niczego nie zmieni. W takim przypadku przekaż programiście kod odpowiedzi z dziennika.

Kliknięcie dostawy otwiera stronę Szczegóły dostawy z treścią wysłanego powiadomienia i odpowiedzią serwera. Przycisk Wyślij ponownie wysyła to samo powiadomienie jeszcze raz, a nowa próba pojawi się w dzienniku. Dziennik przechowuje dostawy z ostatnich 90 dni.

Wygasanie i zmiana sekretuKopiuj link do sekcji

Sekret jest ważny przez okres wybrany w polu Ważność sekretu. Osoby z rolą Właściciel i Administrator dostają e-mail z przypomnieniem 14 dni i 1 dzień przed wygaśnięciem. Po wygaśnięciu panel wyłącza webhook, oznacza go statusem Sekret wygasł i wysyła kolejną wiadomość.

Nowy sekret generuje się tak:

1. Na stronie webhooka kliknij Wygeneruj nowy sekret.
2. W polu Poprzedni sekret przestanie działać wybierz, jak długo stary sekret ma jeszcze działać, od Natychmiast do Za 24 godziny.
3. Kliknij Wygeneruj.
4. Skopiuj nowy sekret w oknie Sekret webhooka i przekaż go programiście.

Przez wybrany czas powiadomienia są podpisywane oboma sekretami. Programista może w tym czasie wymienić sekret bez przerwy w działaniu integracji. Jeśli sekret mógł trafić w niepowołane ręce, wybierz Natychmiast. Wyłączony webhook, np. po wygaśnięciu sekretu, zostanie przy tym ponownie włączony.

Wyłączanie i usuwanieKopiuj link do sekcji

Przełącznik Aktywny na liście albo w sekcji Stan webhooka na stronie webhooka wstrzymuje wysyłkę bez usuwania ustawień. Powiadomienia o zmianach z okresu wyłączenia nie zostaną wysłane także po ponownym włączeniu webhooka.

Webhook usuwa się przyciskiem Usuń webhook w sekcji Usunięcie webhooka na stronie webhooka albo ikoną kosza na liście.

Co dalejKopiuj link do sekcji

Utworzenie webhooka, zmiana sekretu, test i inne zmiany w webhookach trafiają do rejestru zdarzeń:

Rejestr aktywności

Jak sprawdzić, kto, kiedy i co zmienił w panelu. Rejestr zdarzeń organizacji, czyli historia zmian i dziennik audytu z filtrami, szczegółami zmian przed i po oraz zmianami wprowadzonymi przez system i klucze API.

Klucze API

Jak utworzyć klucz API dla programu, który ma sam odczytywać albo zmieniać dane w panelu, np. CRM, ERP albo strony internetowej. Uprawnienia, zakres, okres ważności, dozwolone adresy IP, bezpieczne przekazanie klucza, dziennik żądań i unieważnienie.

Najczęstsze pytaniaKopiuj link do sekcji