Webhooki — zdarzenie po rozmowie

Clovie może powiadomić Twój system o każdej zakończonej rozmowie. Typowe zastosowania: utworzenie karty w CRM, uruchomienie workflow w n8n albo Make, dopisanie wiersza w arkuszu.

Konfiguracja

1. Panel → Integracje → Webhook zakończenia rozmowy.
2. Wklej adres swojego endpointu i zapisz.
3. Skopiuj sekret podpisu — pokazujemy go tylko raz. Służy do weryfikacji, że żądanie faktycznie pochodzi od nas.

Webhook jest ustawiany per asystent — każdy może wysyłać gdzie indziej. Przełącznik Aktywny / Wstrzymany pozwala go czasowo wyłączyć bez utraty konfiguracji, a Nowy sekret rotuje klucz podpisu.

Co dostaniesz

POST <Twój URL>
X-Clovie-Event: conversation.ended
X-Clovie-Delivery: <uuid dostawy>
X-Clovie-Signature: sha256=<HMAC-SHA256 treści żądania>

W treści: identyfikatory organizacji, asystenta i rozmowy, czas rozpoczęcia i zakończenia, powód zakończenia oraz podsumowanie — liczba wiadomości, liczba odpowiedzi asystenta oraz informacja, czy doszło do rezerwacji lub przejęcia rozmowy przez człowieka.

Powód zakończenia to jedna z trzech wartości:

Wartość	Znaczenie
visitor_closed	Gość zamknął czat
consultant_closed	Rozmowę zamknął konsultant
inactive_timeout	Minęły 24 godziny bez aktywności

Payload nie zawiera treści wiadomości ani danych osobowych. To decyzja projektowa, nie przeoczenie: webhook zwykle idzie do systemu trzeciego, a wysyłanie tam transkryptów rozmów z klientami tworzyłoby obowiązki wynikające z RODO, których nie da się cofnąć. Treść rozmowy pobierzesz z panelu albo przez API, świadomie.

Weryfikacja podpisu

Policz HMAC-SHA256 z surowej treści żądania, używając swojego sekretu, i porównaj z nagłówkiem X-Clovie-Signature. Liczenie z sparsowanego i ponownie zserializowanego JSON-a da inny wynik — kolejność kluczy i białe znaki muszą się zgadzać.

Żądania, których podpis się nie zgadza, odrzucaj.

Ponowienia i duplikaty

Jeśli Twój endpoint nie odpowie sukcesem, ponawiamy pięć razy z rosnącym odstępem: natychmiast, po minucie, po 5 minutach, po 30 minutach i po 2 godzinach. Limit czasu pojedynczej próby to 10 sekund.

Na rozmowę przypada jedna dostawa, ale przy ponowieniach ta sama treść może dotrzeć więcej niż raz — na przykład gdy Twój serwer przetworzył żądanie, a odpowiedź nie zdążyła wrócić. Odfiltruj duplikaty po X-Clovie-Delivery, a operację po swojej stronie zrób idempotentną.

Odpowiadaj szybko: przyjmij zdarzenie, zwróć 200 i przetwórz je asynchronicznie. Ciężka praca wykonywana w trakcie żądania kończy się timeoutem i niepotrzebnym ponowieniem.