Webhookok és kézbesítés

A Hanc.AI minden hívás után el tudja küldeni a hívást – összefoglaló, átirat, kinyert mezők – az Ön saját rendszerébe: jegykezelő rendszerbe, CRM-be, ERP-be vagy bármely HTTPS-végpontra. Ez az oldal azt írja le, pontosan hogyan viselkedik ez a kézbesítés: mi történik, ha a szervere nem érhető el, milyen gyakran próbálkozunk újra, mit kell átengednie a tűzfalának, és hogyan néz ki a kérés.

Minden csomag

A hívás utáni kézbesítés az újrapróbálkozásokkal és a kézbesítési naplóval együtt minden csomagban elérhető, beleértve a Free-t is.

Mit küldünk, és mikor

A kérés akkor indul el, amikor a hívás véget ért, és az elemzése elkészült (összefoglaló, hangulat, a kinyert mezői) – jellemzően néhány másodperccel a vonal bontása után.

Forrás	Hol állítható be
API hívás művelet	Ügynök → Műveletek → Post call → API hívás
Munkafolyamat-lépés	Munkafolyamat-szerkesztő → API-hívás eszközlépés Mikor fut: A hívás után beállítással
Ügynök-webhook	Az ügynök `webhook_url` mezője (API-referencia)

Azok a kérések, amelyeket az ügynök a beszélgetés közben indít (élő eszközök), nem tartoznak ide: ezekre abban a pillanatban van szükség, és később soha nem ismétlődnek meg.

Ha a szervere nem érhető el

Semmi sem vész el. A kérés már az első próbálkozás előtt bekerül egy kézbesítési sorba, és ott marad, amíg a szervere el nem fogadja, vagy az ütemezés le nem jár.

A kézbesítés akkor számít sikeresnek, ha a végpontja 30 másodpercen belül bármilyen 2xx státusszal válaszol.
Minden más esetben újrapróbálkozunk: elutasított kapcsolat, DNS- vagy TLS-hiba, időtúllépés és bármely más státusz esetén – 5xx, 429, sőt 4xx esetén is. Ha lejárt egy API-kulcs, és megújítja, a függőben lévő hívások maguktól megérkeznek.
Minden próbálkozás ugyanazt a kérést küldi, ugyanazzal a kézbesítési azonosítóval.

Az újrapróbálkozások ütemezése

Próbálkozás	Szünet előtte	A hívás vége óta eltelt idő
1	– (azonnal)	~0
2	1 perc	~1 perc
3	5 perc	~6 perc
4	30 perc	~36 perc
5	2 óra	~2 óra 36 perc
6	6 óra	~8 óra 36 perc
7	24 óra	~1 nap 8 óra
8	48 óra	~3 nap 8 óra

Ez 8 próbálkozás körülbelül 3,4 nap alatt – elegendő egy hétvégi kiesés áthidalásához.

Saját ütemezés

Az API hívás műveletben (és a munkafolyamat hívás után futó API-hívás lépésében) az Újrapróbálkozások hiba esetén alatt lecserélheti az ütemezést:

legfeljebb 10 újrapróbálkozás,
minden szünet 1 perc és 7 nap közötti,
ha minden sort eltávolít, a kérés egyszer megy ki, újrapróbálkozás nélkül.

Az a művelet, amelyhez soha nem nyúlt, a fenti alapértelmezett ütemezést követi.

Az utolsó próbálkozás után

A kézbesítés Nincs kézbesítve jelölést kap, Önt e-mailben értesítjük – hacsak ezt ki nem kapcsolta –, a kérést pedig 30 napig megőrizzük. Ez idő alatt újraküldheti – egyetlen kattintással a kézbesítési naplóban vagy egyetlen API-hívással. Az újraküldés már sikeres kézbesítésnél is lehetséges, például az Ön oldalán végzett visszaállítás után.

Minden webhooktól függetlenül maga a hívás megmarad a Hanc.AI-fiókjában – az átirat, az összefoglaló, a felvétel és a kinyert mezők a Hívások alatt és az API-n keresztül is elérhetők. Egy hosszabb kiesés késlelteti az átadást a rendszerének; a beszélgetést nem törli.

Legalább egyszer

A kézbesítés legalább egyszer megtörténik. Ritka esetben – például ha a szervere feldolgozott egy kérést, de a válasz nem ért el hozzánk időben – ugyanaz a hívás kétszer érkezik meg. Az X-Hanc-Delivery-Id alapján felismerheti és kihagyhatja az ismétlést.

Értesítések hiba esetén

Nem kell figyelnie a naplót: egy művelet e-mailben jelezheti, ha a kérését nem sikerült kézbesíteni. A műveletben (vagy a munkafolyamat-lépésben) az Értesítés hiba esetén alatt választhat:

Beállítás	Mikor megy ki az e-mail
Az utolsó próbálkozás után (alapértelmezett)	Egyszer, amikor az újrapróbálkozások ütemezése kimerült, és a kérés Nincs kézbesítve jelölést kap
Minden sikertelen próbálkozás után	Minden sikertelen próbálkozás után, a következő időpontjával – és az utolsó után is
Ne értesítsen	Soha; a hibák csak a naplóban láthatók

Az e-mail megnevezi a műveletet és az ügynököt, a szervere gazdagépnevét, azt, hogy a szerver mit válaszolt (például HTTP 503 vagy timeout after 30s), és hogy ez az összesből hányadik próbálkozás volt, továbbá hivatkozást ad a kézbesítési naplóra. Az utolsó e-mail azt is közli, meddig őrizzük meg a kérést, és hogy újra elküldhető.

A Címzett mező adja meg, ki kapja az e-mailt – jellemzően az, aki a fogadó rendszert üzemelteti. Ha üresen marad, az e-mail a fiók tulajdonosának megy. Az e-mail a fiók nyelvén készül.

Hogy egy kiesés ne árassza el a postafiókját, az értesítések száma műveletenként óránként 10-re és naponta 30-ra van korlátozva; a szüneteltetés előtti utolsó értesítés közli, meddig tart a szüneteltetés. Minden hiba továbbra is bekerül a naplóba. A kézzel újraküldött kérésről nem megy értesítés.

Kézbesítési napló

Minden próbálkozást rögzítünk: az időpontot, a HTTP-státuszt vagy a hálózati hibát, az időtartamot és a szervere válaszának elejét.

Az alkalmazásban: CRM → Kommunikáció → nyisson meg egy API-hívás típusú bejegyzést. Itt látható az állapot (Kézbesítve, Újrapróbálkozás, Nincs kézbesítve), az összes próbálkozás, a következő időpontja és a Küldés újra gomb.

Az API-n keresztül (hitelesítés az API-kulcsával az x-api-key fejlécben):

Kérés	Eredmény
`GET /v1/webhook-deliveries`	A kézbesítései, a legújabbal kezdve. Szűrők: `status` (`pending`, `delivered`, `failed`), `agent_id`, `call_id`, `limit`, `offset`
`GET /v1/webhook-deliveries/{id}`	Egy kézbesítés az összes próbálkozással és a kérés törzsével
`POST /v1/webhook-deliveries/{id}/resend`	Azonnal újraküldi, és visszaadja az eredményt

{
  "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" }
  ]
}

A tárolt kérés fejlécértékeit (az Ön kulcsait) soha nem adjuk vissza.

Hálózat és tűzfal

A Hanc.AI az Ön végpontját hívja meg – a kapcsolat mindig a mi oldalunkról nyílik az Ön oldala felé.


Irány	Kimenő a Hanc.AI felől → bejövő az Ön oldalán
Forrás IP-címek	`178.104.10.47` (kézbesítési szolgáltatás) és `128.140.65.92` (hívásszolgáltatás, tartalék útvonalként)
Protokoll	HTTPS (TLS 1.2 vagy újabb). A titkosítatlan HTTP működik, de nem ajánlott
Port	`443`, vagy az URL-jében megadott port
IP-verzió	IPv4
Tanúsítvány	Érvényesnek kell lennie, és nyilvános hitelesítésszolgáltatónak kell kiállítania; az önaláírt tanúsítványokat elutasítjuk
Válaszidő	Válaszoljon 30 másodpercen belül – a legjobb azonnal nyugtázni, és a háttérben feldolgozni
Átirányítások	Követjük őket, legfeljebb 5-öt

Engedélyezőlista: ha a tűzfala vagy a WAF forráscím szerint szűr, engedélyezze a fenti két címet a webhook útvonalához. E címek változását előre bejelentjük.

Nem lehetséges: magánhálózaton belüli címek (10.x, 172.16–31.x, 192.168.x, localhost). A végpontnak az internetről elérhetőnek kell lennie – közvetlenül vagy a reverse proxyján / API-átjáróján keresztül.

Böngésző: a webhookok szerverek között futnak. Böngészőbeállítások, bővítmények vagy a munkatársak munkaállomásain megnyitott portok nem játszanak szerepet.

A kérés formátuma

A POST, a PUT és a PATCH kérés JSON-törzset visz (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"
}

Mező	Tartalom
`call_summary`	A beszélgetés összefoglalója
`transcription`	A teljes beszélgetés megszólalásonként, időbélyegekkel
`call_from`, `call_to`, `direction`	Hívó, hívott szám, bejövő vagy kimenő
`start_timestamp`, `end_timestamp`, `duration`	Unix-idő és időtartam ezredmásodpercben
`custom_analysis_data`	Az Ön saját mezői, a beszélgetésből kinyerve – lásd: Lekérdezési változók
`collected_data`	Az ügynök által a hívás közben gyűjtött adatok
`sentiment`, `task_achieved`	A beszélgetés hangulata, és hogy teljesült-e a célja
`recording_url`	A felvétel hivatkozása, ha a felvétel be van kapcsolva
`transfer_history`	A hívás közben történt átadások

A GET és a DELETE esetén ugyanezek a mezők a lekérdezési karakterláncban utaznak; a beágyazott értékek, például a transcription, kimaradnak.

Fejlécek

Fejléc	Jelentés
`X-Hanc-Delivery-Id`	A kézbesítést azonosítja. Minden próbálkozásnál azonos – ezzel szűrhetők ki az ismétlődések
`X-Hanc-Attempt`	A próbálkozás sorszáma, `1`-től kezdve
`X-Correlation-Id`	Belső nyomkövetési azonosító; adja meg, ha az ügyfélszolgálathoz fordul
`User-Agent`	`HANC-Webhooks/1.0`
az Ön fejlécei	Minden, amit a műveletben beállított

Hitelesítés

Ön dönti el, miről ismer fel minket a végpontja:

API-kulcs vagy token – adjon a művelethez egy fejlécet, pl. Authorization: Bearer <token> vagy X-API-Key: <key>. A fejléceket minden próbálkozással elküldjük.
Basic auth – Authorization: Basic <base64(user:password)>.
Lekérdezési paraméter – olyan rendszerekhez, amelyek a kulcsot az URL-ben várják.
Forráscím – csak a fent felsorolt IP-címeket engedélyezze.

A módszerek kombinálhatók; a szokásos beállítás egy kulcs és egy IP-engedélyezőlista együtt.

A kérés igazítása a saját rendszerhez

Alapértelmezés szerint a kérés a teljes hívást tartalmazza (lásd: A kérés formátuma). Olyan rendszer esetén, amely a saját szerkezetét várja – a legtöbb jegykezelő rendszer ilyen –, ezt a szerkezetet Ön írja le, és a hívás adataival tölti ki.

Változók

A hívás utáni API hívás műveletben és a munkafolyamat API-hívás lépésében az URL, a fejlécek, a lekérdezési paraméterek és a törzs dupla kapcsos zárójelbe írt változókat fogadnak. Ezeket közvetlenül a kérés elküldése előtt töltjük ki a hívás adataival.

Változó	Érték
`{{call_id}}`	A hívás azonosítója
`{{call_from}}`, `{{call_to}}`	A hívó és a hívott szám
`{{customer_phone}}`, `{{customer_email}}`	A másik fél telefonszáma és e-mail-címe, a hívás irányától függetlenül
`{{call_direction}}`, `{{call_type}}`	`inbound` / `outbound`, `phone` / `web`
`{{call_start}}`, `{{call_end}}`	Kezdés és befejezés, ISO 8601 (UTC)
`{{call_duration}}`	Időtartam másodpercben
`{{call_summary}}`	A beszélgetés összefoglalója
`{{call_transcription}}`	A teljes beszélgetés szövegként
`{{call_sentiment}}`, `{{call_task_achieved}}`	A hangulat, és hogy teljesült-e a cél
`{{call_recording_url}}`	A felvétel hivatkozása
`{{agent_id}}`	Az ügynök azonosítója
az Ön mezői	Minden lekérdezési változó a saját nevén, pl. `{{customer_number}}`, `{{priority}}` – valamint minden változó, amelyet egy munkafolyamat a hívás közben gyűjtött

Amit érdemes tudni:

Az a törzsmező, amely egyetlen változóból áll, megtartja a változó típusát: a "priority": "{{priority}}" a 3 számként, az "urgent": "{{urgent}}" pedig true értékként megy ki. Ha a változó körül szöveg is áll, az érték szöveg lesz.
Az URL-be helyezett értéket automatikusan százalékkódoljuk (a +43… helyett %2B43… lesz).
Az a változó, amelyhez a hívásban nincs érték, üresen megy ki – soha nem a szó szerinti {{name}} formában.

Az alkalmazásban egy mező {x} gombja felsorolja az elérhető változókat; a törzsben a {{ beírására megjelennek a javaslatok.

Törzs

A művelet Törzs (JSON) mezőjébe azt a JSON-objektumot írja, amelyet a rendszere vár, tetszőleges mélységben egymásba ágyazva:

{
  "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"]
  }
}

Csak a saját mezők

Ha a Csak a saját mezőim küldése be van kapcsolva, a kérés kizárólag az Ön törzsét és lekérdezési paramétereit tartalmazza – a hívásadatok nem kerülnek bele. Ha kikapcsolva hagyja, a mezőit a teljes hívással együtt küldjük el.

Szelektív küldés

Egy hétköznapi nyelven megfogalmazott feltétel („csak ha a hívó hibát jelent be”) dönti el, mely hívások váltják ki a kérést. Több művelet különböző rendszerekre vagy végpontokra is mutathat.

Jegykezelő rendszer csatlakoztatása

Bármely jegykezelő rendszer fogadhat hívásokat, amelynek van HTTP API-ja vagy bejövő webhookja – közvetlenül, közbeiktatott szoftver nélkül. Az Ön oldalán a következőkre van szükség:

Egy végpont, amely az internetről HTTPS-en keresztül elérhető, és JSON-t fogad.
Egy hitelesítő adat hozzá (API-kulcs, token vagy basic auth), a műveletben fejlécként megadva.
Ha cím szerint szűr – a fenti két IP-cím az engedélyezőlistáján.

Ezután a műveletben:

Határozza meg a mezőit. Vegyen fel lekérdezési változókat, például ügyfélszám, jegykategória, prioritás, visszahívást kér. Az ügynök a beszélgetés alapján tölti ki őket.
Írja meg a törzset a jegykezelő API-ja szerkezetében, és helyezze a változókat a megfelelő helyre.
Kapcsolja be a Csak a saját mezőim küldése kapcsolót.
Kattintson az API konfiguráció tesztelése gombra, majd indítson egy teszthívást.

A rendszeréhez illő törzset szívesen előkészítjük Önnel közösen.

Tesztelés

Kapcsolatteszt. A művelet API konfiguráció tesztelése gombja azonnal elküld egy mintakérést, és megmutatja, sikerült-e elérni a végpontját.

Az újrapróbálkozások tesztje – hogy a saját szemével lássa a mechanizmust:

A műveletben az Újrapróbálkozások hiba esetén alatt állítson be rövid ütemezést, például három 1 perces szünetet.
Állítsa le a végpontját, vagy tiltsa le a címeinket a tűzfalon.
Indítson teszthívást az ügynökhöz.
Nyissa meg a CRM → Kommunikáció oldalt: a bejegyzésnél az Újrapróbálkozás állapot, a sikertelen próbálkozás a hibájával és a következő próbálkozás időpontja látható.
Indítsa el újra a végpontot (vagy oldja fel a tiltást). A következő próbálkozás kézbesíti a hívást, és a bejegyzés Kézbesítve állapotra vált – vagy kattintson a Küldés újra gombra az azonnali kézbesítéshez.

Ellenőrzőlista a végpontjához

Válaszoljon 2xx státusszal, amint a kérést eltárolta; a nehezebb munkát utána végezze el.
Kezelje az X-Hanc-Delivery-Id értéket idempotenciakulcsként.
Válaszoljon 4xx/5xx státusszal, ha nem tudta átvenni a kérést – újra jelentkezünk.
Tartsa érvényesen a tanúsítványt, és hagyja engedélyezve a két forráscímet.

Mit küldünk, és mikor​

Ha a szervere nem érhető el​

Az újrapróbálkozások ütemezése​

Saját ütemezés​

Az utolsó próbálkozás után​

Értesítések hiba esetén​

Kézbesítési napló​

Hálózat és tűzfal​

A kérés formátuma​

Fejlécek​

Hitelesítés​

A kérés igazítása a saját rendszerhez​

Változók​

Törzs​

Csak a saját mezők​

Szelektív küldés​

Jegykezelő rendszer csatlakoztatása​

Tesztelés​

Ellenőrzőlista a végpontjához​