Webhooki: konfiguracja i weryfikacja pochodzenia wywołań

Webhook to wiadomość, którą Quanda sama wysyła na adres Twojego systemu, gdy nastąpi zdarzenie, na przykład kliknięcie linku, otwarcie e-maila, wypisanie, wysłanie e-maila albo zapisanie wypełnionej ankiety. Webhookami zarządzasz w Quandzie w Ustawieniach / Webhook. Każdy webhook może zawierać własny nagłówek z tajnym tokenem, po którym Twój system sprawdzi, że wywołanie naprawdę wysłała Quanda.

Jak dodać i edytować webhook

Listę webhooków znajdziesz w Ustawieniach / Webhook. W oknie dodawania i edycji webhooka podajesz adres, na który Quanda ma wysyłać wywołania, oraz zdarzenie, przy którym webhook ma zostać wysłany.

Okno zawiera też opcjonalne pola własnego nagłówka:

• Nazwa nagłówka: nazwa, pod którą Quanda doda wartość do wywołania, na przykład X-Webhook-Token.
• Wartość nagłówka: tajny token, który Twój system porówna ze swoją zapisaną wartością. Przy zapisanym webhooku pole pokazuje tylko maskę.
• Usuń nagłówek: opcja widoczna przy webhooku z nagłówkiem. Po zapisaniu Quanda przestanie dodawać nagłówek do wywołań.

Oba pola możesz zostawić puste. Webhook działa wtedy tak samo jak dotąd.

Co oznacza ikona kłódki na liście webhooków

Ikona kłódki na liście oznacza webhook zabezpieczony własnym nagłówkiem. Webhook bez kłódki nie ma nagłówka i Quanda wywołuje go bez niego.

Weryfikacja pochodzenia wywołań własnym nagłówkiem

Nagłówek to dodatkowa informacja żądania HTTP w postaci nazwy i wartości, wysyłana razem z wywołaniem, ale poza jego treścią. Token to losowy ciąg znaków, który znasz tylko Ty i Quanda, i działa podobnie jak hasło.

Wywołanie webhooka bez nagłówka nie zawiera żadnej informacji, po której odbiorca rozpoznałby nadawcę. Każdy, kto zna adres, może wysłać na niego sfałszowane wywołanie. Własny nagłówek temu zapobiega.

Jak to działa

Quanda dodaje ustawiony nagłówek do każdego wywołania webhooka. Twój system porównuje wartość nagłówka z wartością, którą ma zapisaną, i przetwarza wywołanie tylko wtedy, gdy są zgodne.

Jako token wybierz losowy ciąg o długości co najmniej 32 znaków i nie używaj go nigdzie poza Quandą. Wywołania bez poprawnego nagłówka odrzucaj w swoim systemie odpowiedzią ze statusem 401.

Treść wywołania, czyli jego ciało, się nie zmienia. Funkcja jest opcjonalna, a webhooki bez nagłówka działają dokładnie tak jak dotąd.

Jak ustawić nagłówek

1. W Quandzie otwórz Ustawienia / Webhook.
2. Dodaj nowy webhook albo otwórz edycję istniejącego.
3. Sprawdź, czy adres webhooka zaczyna się od https://.
4. W polu Nazwa nagłówka wpisz nazwę, na przykład X-Webhook-Token.
5. W polu Wartość nagłówka wklej tajny token.
6. Zapisz webhook. Na liście pojawi się przy nim ikona kłódki.

Zapisz token w swoim systemie, zanim zapiszesz webhook. Zapisanej wartości Quanda już nigdzie nie pokaże.

Jak zmienić albo usunąć nagłówek

• Edycja webhooka bez zmiany nagłówka: pole Wartość nagłówka zostaw puste. Nagłówek pozostanie taki, jak jest zapisany.
• Zmiana tokenu: w polu Wartość nagłówka wpisz nową wartość i zapisz webhook. Nowa wartość obowiązuje od następnego wywołania, dlatego w tej samej chwili zmień ją także w swoim systemie.
• Usunięcie nagłówka: wybierz Usuń nagłówek i zapisz webhook. Ikona kłódki zniknie z listy.

Warunki i ograniczenia

• Adres https://: protokół https przesyła dane w postaci zaszyfrowanej. Webhook z nagłówkiem musi mieć adres zaczynający się od https://, a serwer docelowy musi mieć ważny certyfikat. Na nieszyfrowany adres Quanda nagłówka nie wyśle.
• Nazwa nagłówka: może zawierać litery, cyfry i łącznik oraz mieć najwyżej 64 znaki. Nagłówek Authorization jest dozwolony. Niektóre nazwy techniczne nie są dozwolone, na przykład Host, Content-Type, Cookie oraz nazwy zaczynające się od X-Quanda-.
• Wartość nagłówka: może zawierać znaki drukowalne bez znaków diakrytycznych i mieć najwyżej 1024 znaki.
• Liczba nagłówków: w aplikacji ustawisz przy webhooku jeden nagłówek, przez API do 5. Webhook z kilkoma nagłówkami ustawionymi przez API nie pokazuje w aplikacji pól nagłówka i edytujesz go przez API.
• Wyświetlanie wartości: zapisana wartość nie jest pokazywana ani w aplikacji, ani w API. Widzisz tylko maskę, czyli cztery gwiazdki i ostatnie 4 znaki. Przy wartościach krótszych niż 12 znaków widać same gwiazdki.

Jak Quanda dostarcza webhooki

Twój system powinien odpowiedzieć na wywołanie statusem 200. Przy innej odpowiedzi Quanda powtarza wywołanie, do 5 razy:

1. po 30 sekundach,
2. po 5 minutach,
3. po 50 minutach,
4. po około 8 godzinach,
5. po około 83 godzinach.

Tak samo Quanda postępuje, gdy Twój system odrzuci wywołanie z powodu nagłówka. Własny nagłówek nie zmienia dostarczania.

Dokumentacja dla programistów

Webhooki możesz tworzyć i edytować także przez API. Nagłówki ustawia się w polu headers przy tworzeniu i edycji webhooka, czyli w wywołaniach POST, PUT i PATCH na /api/webhook/webhooks/. Edycja webhooka bez zmian wywołaniem PUT nie zwraca już błędu, a częściowa edycja wywołaniem PATCH nie wymaga pola event.

Opis wszystkich wywołań i struktury wiadomości znajdziesz w języku angielskim w dokumentacji API, w części Webhooks. Jak uzyskać klucz API, opisuje artykuł Dokumentacja API i klucz API.

Własny nagłówek jest dostępny bez dopłaty dla wszystkich kont, które mają dostęp do Ustawień / Webhook i do API.

Jeśli sobie nie radzisz albo masz pytanie, śmiało skontaktuj się z naszym wsparciem klienta pod adresem support@onquanda.com albo telefonicznie pod numerem +48 886 080 501.