Dane ze wsparcia rzadko zostają w jednym narzędziu. Rozmowa może utworzyć notatkę w CRM, założyć zadanie, powiadomić inżynierię, zaktualizować kartę klienta albo zasilić raport. Część tej pracy powinna być pobierana przez API. Część powinna wydarzyć się od razu po zdarzeniu. Dlatego Convor udostępnia REST API i webhooki wychodzące.
Traktuj API jako stabilną granicę
Wygeneruj klucz API w panelu i wysyłaj go jako Bearer token. Klucz jest zawężony do organizacji, więc kod integracji nie powinien zakładać globalnej domyślnej organizacji. To szczególnie ważne, gdy jedna usługa integracyjna obsługuje wielu klientów. Trzymaj granicę organizacji jawnie i nie buduj automatyzacji na sesjach z przeglądarki ani zachowaniu dostępnym tylko w panelu.
Paginacja kursorem jest tam nie bez powodu
Listy rozmów i wiadomości rosną podczas odczytu. Paginacja offsetem potrafi pominąć albo zdublować rekordy, gdy między żądaniami pojawią się nowe wiersze. Paginacja kursorem kontynuuje od znanego punktu w uporządkowanym strumieniu. Dla integracji oznacza to zapis kursora albo high-water mark, bezpieczne ponowne przetwarzanie stron i założenie, że lista zmienia się w trakcie pracy.
Webhooki są próbami dostarczenia
Webhook nie jest rozproszoną transakcją. Twój endpoint może być wyłączony, wolny, w trakcie deploya, ograniczony limitem albo chwilowo źle skonfigurowany. Convor wysyła webhooki przez kolejkę, żeby odwiedzający nie czekał na zewnętrzny system. Po Twojej stronie receiver powinien zweryfikować żądanie, zapisać zdarzenie, szybko odpowiedzieć i cięższą pracę wykonać później.
Weryfikuj podpis
Każdy webhook zawiera podpis HMAC. Użyj sekretu z ustawień webhooka i weryfikuj surowe body żądania, jeśli framework na to pozwala. Nie parsuj JSON-a, nie serializuj go ponownie i nie weryfikuj zmienionego tekstu. Białe znaki oraz kolejność kluczy mogą się zmienić. Jeśli obsługujesz sprawdzanie timestampu, odrzucaj stare żądania, żeby ograniczyć ryzyko replay.
Spodziewaj się duplikatów
Niezawodna wysyłka webhooków może dostarczyć to samo zdarzenie więcej niż raz. Receiver powinien być idempotentny. Zapisz ID zdarzenia albo zbuduj deterministyczny klucz z payloadu, zanim utworzysz obiekty po drugiej stronie. Jeśli ta sama notatka CRM pojawia się dwa razy, receiver prawdopodobnie nie zrobił deduplikacji. Bezpieczny schemat jest prosty: zweryfikuj, zapisz, potwierdź, potem przetwarzaj.
Użyj REST API, gdy Twój system potrzebuje zapytać o stan. Użyj webhooków, gdy Twój system ma zareagować na zdarzenie. Większość poważnych integracji używa obu, bo rozwiązują różne części problemu.
Nowe wpisy na Twoją skrzynkę
Bez spamu. Wypisz się w dowolnej chwili.
