API i webhooki - wymagania i zasady działania

API i webhooki Welyo umożliwiają integrację Welyo CX Platform z systemami zewnętrznymi. API wykorzystujemy do wykonywania operacji oraz pobierania danych, a webhooki do przekazywania informacji po wystąpieniu określonych zdarzeń w Welyo.

Zakres dostępnych funkcji zależy od obsługiwanej wersji API, konfiguracji domeny oraz zakresu usług dostępnych dla klienta.

Dokumentacja API

Szczegółowa dokumentacja API jest dostępna w panelu administratora Welyo. Zawiera aktualnie dostępne endpointy, parametry żądań i odpowiedzi oraz informacje wymagane do korzystania z poszczególnych operacji.

Sposób otwarcia dokumentacji opisujemy w artykule: Dokumentacja API w panelu administratora

Dodatkowe informacje dotyczące korzystania z API znajdziemy w sekcji: API Welyo

Obsługiwane wersje API

Aktualnie obsługiwane są:

• API v3,
• API v4.

W okresie równoległego wsparcia mogą być dostępne bieżąca i poprzednia wersja API.

Jeżeli zmiana endpointu nie może zostać wprowadzona z zachowaniem zgodności z dotychczasową wersją, udostępniana jest jego nowa wersja. Kolejna niekompatybilna zmiana może więc zostać udostępniona w kolejnej wersji API, np. v5.

Autoryzacja i bezpieczeństwo dostępu

Korzystanie z API wymaga autoryzacji zgodnej z dokumentacją właściwej wersji API. Szczegółowy sposób autoryzacji, w tym wymagane dane dostępowe i tokeny, jest opisany w dokumentacji API dostępnej w panelu administratora.

Klient odpowiada za:

• zabezpieczenie kluczy, tokenów i innych danych dostępowych,
• udostępnianie danych dostępowych wyłącznie uprawnionym osobom i systemom,
• nadawanie integracjom minimalnego zakresu uprawnień niezbędnego do ich działania,
• prawidłową konfigurację własnych systemów korzystających z API,
• aktualizację danych dostępowych, jeżeli zostaną zmienione lub unieważnione.

Limity techniczne API

Wywołania API podlegają limitom technicznym określonym dla domeny.

Wywołania przekraczające limit mogą zostać ograniczone, zakolejkowane lub nieprzyjęte w celu ochrony stabilności usługi.

Przekroczenie limitu technicznego nie powoduje automatycznego naliczenia dodatkowej opłaty.

Szczegółowe wartości limitów znajdziemy w artykule dotyczącym limitów technicznych Welyo.

Webhooki

Webhooki służą do automatycznego przekazywania informacji o zdarzeniach występujących w Welyo do wskazanego systemu zewnętrznego.

W konfiguracji webhooka określamy między innymi:

• zdarzenie uruchamiające webhook,
• adres docelowy,
• dane autoryzacyjne wymagane przez system odbierający.

Instrukcję konfiguracji znajdziemy w artykule: Jak skonfigurować webhooki w kampanii?

Dostępne zdarzenia webhooków

Aktualna lista obsługiwanych zdarzeń oraz dokumentacja poszczególnych webhooków znajduje się w sekcji: Webhooki

Zakres danych przekazywanych dla konkretnego zdarzenia określa dokumentacja właściwego webhooka.

Ponawianie webhooków

Webhook jest wysyłany jednokrotnie po wystąpieniu skonfigurowanego zdarzenia.

Jeżeli wysłanie webhooka zakończy się niepowodzeniem, Welyo nie wykonuje automatycznej ponownej wysyłki tego samego zdarzenia.

Oznacza to, że dostarczenie webhooka nie jest gwarantowane w sytuacji, gdy system odbierający jest w momencie wysyłki niedostępny lub nie może prawidłowo przyjąć żądania.

System odbierający webhooki powinien uwzględniać możliwość niedostarczenia pojedynczego zdarzenia.

Zmiany API i endpointów

Zmiany, które zachowują zgodność z dotychczasowym sposobem działania endpointu, mogą być wprowadzane w ramach obsługiwanej wersji.

Jeżeli zmiana wymaga modyfikacji endpointu w sposób niezgodny z jego dotychczasowym sposobem użycia, Welyo może udostępnić nową wersję endpointu lub API.

Pozwala to na równoległe utrzymywanie dotychczasowej i nowej wersji przez okres przejściowy oraz dostosowanie integracji po stronie klienta.

Wycofanie wersji API lub endpointu

Planowane wycofanie obsługiwanej wersji API lub endpointu jest zapowiadane co najmniej 90 dni wcześniej.

W przypadku zastępowania wersji nową wersją okres równoległego wsparcia wynosi co najmniej 90 dni.

Informacja o wycofaniu zawiera sposób przejścia na wersję, która pozostaje wspierana.

Po zakończeniu okresu wsparcia wycofana wersja lub endpoint mogą zostać wyłączone.

Zmiany związane z bezpieczeństwem i stabilnością

W przypadku zagrożenia bezpieczeństwa lub stabilności usługi Welyo może czasowo ograniczyć działanie, zmienić lub wyłączyć endpoint albo integrację w zakresie niezbędnym do usunięcia zagrożenia.

Dotyczy to między innymi:

• wykrycia podatności bezpieczeństwa,
• wykorzystania danych dostępowych w sposób stwarzający zagrożenie,
• zapętlonego lub nieprawidłowego ruchu,
• działania wpływającego na bezpieczeństwo lub stabilność Welyo.

W takich przypadkach działania ochronne mogą zostać zastosowane niezależnie od standardowego okresu przewidzianego dla planowanego wycofania wersji.