Webhooki i dostarczanie

Po każdej rozmowie Hanc.AI może wysłać jej dane — podsumowanie, transkrypcję, wyodrębnione pola — do Państwa własnego systemu: systemu zgłoszeń, CRM, ERP lub dowolnego endpointu HTTPS. Ta strona opisuje dokładnie, jak przebiega to dostarczanie: co się dzieje, gdy Państwa serwer nie działa, jak często ponawiamy próby, na co musi zezwalać Państwa zapora sieciowa i jak wygląda żądanie.

Wszystkie plany

Dostarczanie po rozmowie wraz z ponowieniami i dziennikiem dostarczeń jest dostępne w każdym planie, również w planie Free.

Co jest wysyłane i kiedy

Żądanie jest wysyłane, gdy rozmowa się zakończyła i jej analiza jest gotowa (podsumowanie, sentyment, Państwa wyodrębnione pola) — zwykle kilka sekund po rozłączeniu.

Źródło	Gdzie się je konfiguruje
Akcja „Wywołanie API”	Agent → Akcje → Post call → Wywołanie API
Krok przepływu pracy	Kreator przepływów → krok narzędzia Wywołanie API z ustawieniem Kiedy się uruchamia: Po połączeniu
Webhook agenta	Pole `webhook_url` agenta (dokumentacja API)

Żądania, które agent wykonuje w trakcie rozmowy (narzędzia na żywo), nie są tu omawiane: są potrzebne dokładnie w tej sekundzie i nigdy nie są powtarzane później.

Gdy Państwa serwer jest niedostępny

Nic nie przepada. Żądanie jest zapisywane w kolejce dostarczania przed pierwszą próbą i pozostaje w niej do chwili, gdy Państwa serwer je przyjmie albo harmonogram się wyczerpie.

Dostarczenie uznaje się za udane, gdy Państwa endpoint odpowie dowolnym statusem 2xx w ciągu 30 sekund.
Wszystko inne jest ponawiane: odmowa połączenia sieciowego, błędy DNS lub TLS, przekroczenie czasu oczekiwania i każdy inny status — 5xx, 429, a także 4xx. Jeśli klucz API wygasł i zostanie przez Państwa odnowiony, oczekujące rozmowy dotrą same.
Każda próba wysyła to samo żądanie z tym samym identyfikatorem dostarczenia.

Harmonogram ponowień

Próba	Przerwa przed nią	Czas od zakończenia rozmowy
1	— (natychmiast)	~0
2	1 minuta	~1 min
3	5 minut	~6 min
4	30 minut	~36 min
5	2 godziny	~2 godz. 36 min
6	6 godzin	~8 godz. 36 min
7	24 godziny	~1 dzień 8 godz.
8	48 godzin	~3 dni 8 godz.

To 8 prób w ciągu około 3,4 dnia — wystarczająco, by przetrwać awarię trwającą cały weekend.

Własny harmonogram

W akcji Wywołanie API (oraz w kroku przepływu pracy Wywołanie API, który uruchamia się po rozmowie) mogą Państwo zastąpić harmonogram w polu Ponowienia przy błędzie:

do 10 ponowień,
każda przerwa od 1 minuty do 7 dni,
usunięcie wszystkich wierszy oznacza wysyłkę jednorazową, bez ponowień.

Akcja, w której niczego Państwo nie zmieniali, działa według domyślnego harmonogramu podanego wyżej.

Po ostatniej próbie

Dostarczenie zostaje oznaczone jako Nie dostarczono, otrzymują Państwo powiadomienie e-mailem, o ile nie zostało ono wyłączone, a żądanie jest przechowywane przez 30 dni. W tym czasie można je wysłać ponownie — jednym kliknięciem w dzienniku dostarczeń albo jednym wywołaniem API. Ponowna wysyłka jest możliwa także w przypadku dostarczenia, które już się powiodło, na przykład po przywróceniu danych po Państwa stronie.

Niezależnie od jakiegokolwiek webhooka sama rozmowa pozostaje na Państwa koncie Hanc.AI — transkrypcja, podsumowanie, nagranie i wyodrębnione pola są dostępne w sekcji Połączenia oraz przez API. Długa awaria opóźnia przekazanie danych do Państwa systemu; nie usuwa rozmowy.

Co najmniej raz

Dostarczanie odbywa się co najmniej raz. W rzadkich przypadkach — na przykład gdy Państwa serwer przetworzył żądanie, ale odpowiedź nie dotarła do nas na czas — ta sama rozmowa dociera dwukrotnie. Nagłówek X-Hanc-Delivery-Id pozwala rozpoznać i pominąć powtórzenie.

Powiadomienia o błędach

Nie muszą Państwo śledzić dziennika: akcja może powiadomić Państwa e-mailem, gdy jej żądanie nie zostanie dostarczone. Wyboru dokonuje się w polu Powiadomienie o błędzie w akcji (lub w kroku przepływu pracy):

Ustawienie	Kiedy wysyłany jest e-mail
Po ostatniej próbie (domyślnie)	Raz, gdy harmonogram ponowień się wyczerpie, a żądanie zostanie oznaczone jako Nie dostarczono
Po każdej nieudanej próbie	Po każdej nieudanej próbie, z terminem następnej — oraz po ostatniej
Nie powiadamiaj	Nigdy; błędy są widoczne tylko w dzienniku

E-mail podaje akcję i agenta, host Państwa serwera, jego odpowiedź (na przykład HTTP 503 lub timeout after 30s), numer próby i łączną liczbę prób oraz zawiera link do dziennika dostarczeń. Ostatni e-mail informuje dodatkowo, do kiedy żądanie jest przechowywane i że można je wysłać ponownie.

Pole Wyślij do określa odbiorcę — zwykle osobę, która obsługuje system odbierający. Jeśli pozostanie puste, e-mail trafi do właściciela konta. Wiadomość jest pisana w języku konta.

Aby awaria nie zalała Państwa skrzynki, powiadomienia są ograniczone dla każdej akcji do 10 na godzinę i 30 na dobę; ostatnie przed przerwą informuje, do kiedy ona potrwa. Każdy błąd jest nadal zapisywany w dzienniku. Żądanie wysłane ponownie ręcznie nie powoduje powiadomienia.

Dziennik dostarczeń

Każda próba jest rejestrowana: czas, status HTTP lub błąd sieci, czas trwania i początek odpowiedzi Państwa serwera.

W aplikacji: CRM → Komunikacja → proszę otworzyć wpis typu Wywołanie API. Widoczne są: status (Dostarczono, Ponawianie, Nie dostarczono), wszystkie próby, termin następnej oraz przycisk Wyślij ponownie.

Przez API (uwierzytelnianie Państwa kluczem API w nagłówku x-api-key):

Żądanie	Wynik
`GET /v1/webhook-deliveries`	Państwa dostarczenia, od najnowszych. Filtry: `status` (`pending`, `delivered`, `failed`), `agent_id`, `call_id`, `limit`, `offset`
`GET /v1/webhook-deliveries/{id}`	Jedno dostarczenie ze wszystkimi próbami i treścią żądania
`POST /v1/webhook-deliveries/{id}/resend`	Wysyła je ponownie od razu i zwraca wynik

{
  "id": "6ac71fb82e4f72e709a4a566",
  "delivery_id": "0b0f2f0e-6c0f-4f0b-9c55-3c6a3a1f8a11",
  "kind": "api_call",
  "name": "Create ticket",
  "call_id": "6ac71f9d2e4f72e709a4a4f0",
  "status": "pending",
  "attempts_made": 2,
  "attempts_max": 8,
  "next_attempt_at": "2026-10-09T11:36:04.000Z",
  "attempts": [
    { "n": 1, "at": "2026-10-09T11:30:03.512Z", "duration_ms": 212, "error": "connection refused" },
    { "n": 2, "at": "2026-10-09T11:31:04.007Z", "duration_ms": 187, "status_code": 503, "error": "HTTP 503", "response_preview": "Service Unavailable" }
  ]
}

Wartości nagłówków zapisanego żądania (Państwa klucze) nigdy nie są zwracane.

Sieć i zapora sieciowa

Hanc.AI wywołuje Państwa endpoint — połączenie sieciowe jest zawsze nawiązywane z naszej strony do Państwa.


Kierunek	Wychodzący z Hanc.AI → przychodzący po Państwa stronie
Źródłowe adresy IP	`178.104.10.47` (usługa dostarczania) i `128.140.65.92` (usługa obsługi rozmów, używana jako ścieżka zapasowa)
Protokół	HTTPS (TLS 1.2 lub nowszy). Nieszyfrowany HTTP działa, ale nie jest zalecany
Port	`443` lub port wskazany w Państwa adresie URL
Wersja IP	IPv4
Certyfikat	Musi być ważny i wystawiony przez publiczny urząd certyfikacji; certyfikaty samopodpisane są odrzucane
Czas odpowiedzi	Odpowiedź w ciągu 30 sekund — najlepiej od razu potwierdzić odbiór, a przetwarzanie wykonać w tle
Przekierowania	Obsługiwane, maksymalnie 5

Lista dozwolonych adresów: jeśli Państwa zapora sieciowa lub WAF filtruje ruch według adresu źródłowego, proszę zezwolić na oba powyższe adresy dla ścieżki webhooka. Zmianę tych adresów ogłaszamy z wyprzedzeniem.

Niemożliwe: adresy w sieci prywatnej (10.x, 172.16–31.x, 192.168.x, localhost). Endpoint musi być osiągalny z internetu — bezpośrednio albo przez Państwa reverse proxy lub bramę API.

Przeglądarka: webhooki działają między serwerami. Nie biorą w tym udziału żadne ustawienia przeglądarki, rozszerzenia ani otwarte porty na stanowiskach pracowników.

Format żądania

Żądania POST, PUT i PATCH zawierają treść w formacie JSON (Content-Type: application/json, UTF-8).

{
  "call_from": "+431234567890",
  "call_to":   "+439876543210",
  "direction": "inbound",
  "call_type": "phone",
  "call_status": "ended",
  "start_timestamp": 1730000000000,
  "end_timestamp":   1730000187000,
  "duration": 187000,
  "call_summary": "Customer reports a broken router and asks for a callback…",
  "transcription": [
    { "speaker": "agent", "content": "Hello…", "timestamp": 1730000001000 },
    { "speaker": "user",  "content": "Hi…",    "timestamp": 1730000003000 }
  ],
  "task_achieved": true,
  "sentiment": { "sentiment": "neutral", "explanation": "…" },
  "custom_analysis_data": {
    "customer_number": "K-20417",
    "ticket_category": "Hardware",
    "priority": "high"
  },
  "collected_data": { },
  "transfer_history": [ ],
  "recording_url": "https://…",
  "disconnection_reason": "user_hangup"
}

Pole	Zawartość
`call_summary`	Podsumowanie rozmowy
`transcription`	Pełna rozmowa, wypowiedź po wypowiedzi, ze znacznikami czasu
`call_from`, `call_to`, `direction`	Dzwoniący, numer docelowy, połączenie przychodzące lub wychodzące
`start_timestamp`, `end_timestamp`, `duration`	Czas uniksowy i czas trwania w milisekundach
`custom_analysis_data`	Państwa własne pola, wyodrębnione z rozmowy — zob. Zmienne pobierania
`collected_data`	Dane zebrane przez agenta w trakcie rozmowy
`sentiment`, `task_achieved`	Nastrój rozmowy i to, czy jej cel został osiągnięty
`recording_url`	Link do nagrania, jeśli nagrywanie jest włączone
`transfer_history`	Przekazania, do których doszło w trakcie rozmowy

W przypadku GET i DELETE te same pola są przekazywane w ciągu zapytania; wartości zagnieżdżone, takie jak transcription, są pomijane.

Nagłówki

Nagłówek	Znaczenie
`X-Hanc-Delivery-Id`	Identyfikuje dostarczenie. Identyczny przy każdej próbie — pozwala pomijać duplikaty
`X-Hanc-Attempt`	Numer próby, począwszy od `1`
`X-Correlation-Id`	Wewnętrzny identyfikator śledzenia; proszę go podać przy kontakcie z pomocą techniczną
`User-Agent`	`HANC-Webhooks/1.0`
Państwa nagłówki	Wszystko, co skonfigurowali Państwo w akcji

Uwierzytelnianie

To Państwo decydują, po czym Państwa endpoint nas rozpoznaje:

Klucz API lub token — proszę dodać do akcji nagłówek, np. Authorization: Bearer <token> lub X-API-Key: <key>. Nagłówki są wysyłane przy każdej próbie.
Basic auth — Authorization: Basic <base64(user:password)>.
Parametr zapytania — dla systemów, które oczekują klucza w adresie URL.
Adres źródłowy — zezwolenie wyłącznie na wymienione wyżej adresy IP.

Metody można łączyć; typowa konfiguracja to klucz oraz lista dozwolonych adresów IP.

Dopasowanie żądania do własnego systemu

Domyślnie żądanie zawiera całą rozmowę (zob. Format żądania). Dla systemu, który oczekuje własnej struktury — a tak jest w przypadku większości systemów zgłoszeń — opisują Państwo tę strukturę samodzielnie i wypełniają ją danymi z rozmowy.

Zmienne

W akcji Wywołanie API po rozmowie oraz w kroku przepływu pracy Wywołanie API pola URL, nagłówki, parametry zapytania i treść przyjmują zmienne w podwójnych nawiasach klamrowych. Są one wypełniane danymi z rozmowy tuż przed wysłaniem żądania.

Zmienna	Wartość
`{{call_id}}`	Identyfikator rozmowy
`{{call_from}}`, `{{call_to}}`	Dzwoniący i numer docelowy
`{{customer_phone}}`, `{{customer_email}}`	Numer i e-mail drugiej strony, niezależnie od kierunku połączenia
`{{call_direction}}`, `{{call_type}}`	`inbound` / `outbound`, `phone` / `web`
`{{call_start}}`, `{{call_end}}`	Początek i koniec, ISO 8601 (UTC)
`{{call_duration}}`	Czas trwania w sekundach
`{{call_summary}}`	Podsumowanie rozmowy
`{{call_transcription}}`	Pełna rozmowa jako tekst
`{{call_sentiment}}`, `{{call_task_achieved}}`	Nastrój i to, czy cel został osiągnięty
`{{call_recording_url}}`	Link do nagrania
`{{agent_id}}`	Identyfikator agenta
Państwa pola	Każda Zmienna pobierania pod swoją nazwą, np. `{{customer_number}}`, `{{priority}}` — a także każda zmienna zebrana przez przepływ pracy w trakcie rozmowy

Zasady, które warto znać:

Pole treści składające się wyłącznie z jednej zmiennej zachowuje jej typ: "priority": "{{priority}}" jest wysyłane jako liczba 3, a "urgent": "{{urgent}}" jako true. Tekst wokół zmiennej zamienia całość w tekst.
Wartość umieszczona w adresie URL jest automatycznie kodowana procentowo (+43… staje się %2B43…).
Zmienna, dla której rozmowa nie ma wartości, jest wysyłana jako pusta — nigdy jako dosłowne {{name}}.

W aplikacji przycisk {x} w polu wyświetla listę dostępnych zmiennych; w treści podpowiedzi pojawiają się po wpisaniu {{.

Treść

W polu Treść (JSON) w akcji wpisują Państwo obiekt JSON, którego oczekuje Państwa system, zagnieżdżony tak głęboko, jak to potrzebne:

{
  "ticket": {
    "subject": "Call from {{customer_phone}}: {{ticket_category}}",
    "comment": { "body": "{{call_summary}}" },
    "priority": "{{priority}}",
    "custom_fields": [
      { "id": 360001, "value": "{{customer_number}}" },
      { "id": 360002, "value": "{{call_recording_url}}" }
    ],
    "tags": ["phone-agent"]
  }
}

Tylko Państwa pola

Gdy przełącznik Wysyłaj tylko moje pola jest włączony, żądanie zawiera wyłącznie Państwa treść i Państwa parametry zapytania — dane rozmowy nie są dołączane. Gdy pozostaje wyłączony, Państwa pola są wysyłane razem z pełnymi danymi rozmowy.

Wysyłka selektywna

Warunek zapisany zwykłym językiem („tylko jeśli dzwoniący zgłasza awarię”) decyduje o tym, które rozmowy uruchamiają żądanie. Kilka akcji może wskazywać różne systemy lub endpointy.

Podłączanie systemu zgłoszeń

Każdy system zgłoszeń z API HTTP lub przychodzącym webhookiem może odbierać rozmowy — bezpośrednio, bez dodatkowego oprogramowania pośredniczącego. Po Państwa stronie potrzebne są:

Endpoint osiągalny z internetu przez HTTPS, który przyjmuje JSON.
Dane uwierzytelniające do niego (klucz API, token lub basic auth), wpisane w akcji jako nagłówek.
Jeśli filtrują Państwo ruch według adresu — oba adresy IP podane wyżej na Państwa liście dozwolonych.

Następnie w akcji należy:

Zdefiniować własne pola. Proszę dodać Zmienne pobierania, takie jak numer klienta, kategoria zgłoszenia, priorytet, prośba o oddzwonienie. Agent wypełnia je na podstawie rozmowy.
Napisać treść w strukturze API Państwa systemu zgłoszeń i umieścić zmienne we właściwych miejscach.
Włączyć Wysyłaj tylko moje pola.
Kliknąć Testuj konfigurację API, a następnie wykonać połączenie testowe.

Chętnie przygotujemy treść dla Państwa systemu wspólnie z Państwem.

Testowanie

Test łączności. Przycisk Testuj konfigurację API w akcji od razu wysyła przykładowe żądanie i pokazuje, czy udało się dotrzeć do Państwa endpointu.

Test ponowień — aby zobaczyć mechanizm na własne oczy:

W akcji proszę ustawić w polu Ponowienia przy błędzie krótki harmonogram, na przykład trzy przerwy po 1 minucie.
Proszę zatrzymać swój endpoint albo zablokować nasze adresy w zaporze sieciowej.
Proszę wykonać połączenie testowe z agentem.
Proszę otworzyć CRM → Komunikacja: wpis pokazuje status Ponawianie, nieudaną próbę wraz z błędem oraz termin następnej.
Proszę ponownie uruchomić endpoint (lub zdjąć blokadę). Następna próba dostarczy rozmowę, a wpis zmieni status na Dostarczono — można też kliknąć Wyślij ponownie, aby dostarczyć ją natychmiast.

Lista kontrolna dla Państwa endpointu

Odpowiedź 2xx proszę wysyłać, gdy tylko żądanie zostanie zapisane; cięższe przetwarzanie należy wykonać później.
X-Hanc-Delivery-Id proszę traktować jako klucz idempotencji.
Gdy żądania nie udało się przyjąć, proszę odpowiedzieć 4xx/5xx — wrócimy.
Proszę dbać o ważność certyfikatu i o to, by oba adresy źródłowe pozostawały dozwolone.

Co jest wysyłane i kiedy​

Gdy Państwa serwer jest niedostępny​

Harmonogram ponowień​

Własny harmonogram​

Po ostatniej próbie​

Powiadomienia o błędach​

Dziennik dostarczeń​

Sieć i zapora sieciowa​

Format żądania​

Nagłówki​

Uwierzytelnianie​

Dopasowanie żądania do własnego systemu​

Zmienne​

Treść​

Tylko Państwa pola​

Wysyłka selektywna​

Podłączanie systemu zgłoszeń​

Testowanie​

Lista kontrolna dla Państwa endpointu​