Skip to main content
A ThunderPhone HTTP POST kéréseket küld az Ön szerverének, amikor egy hívás során esemény történik — bejövő hívás indul, hívás ér véget, értékelési futás fejeződik be, riasztás aktiválódik stb. Két kézbesítési modell érhető el:

Webhook-végpontok (ajánlott)

Több URL, végpontonkénti titkos kulcsok, végpontonkénti eseményszűrők és automatikus újrapróbálkozások. Kezelés: GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.

Örökölt, egy URL-es webhook

Szervezetenként egy URL. A hívás-életciklus eseményeit tartalmazza, beleértve a blokkoló konfigurációs adatcseréket is. Kezelés: GET/PUT /v1/webhook.
Az eseménykatalógus mind a tíz eseménytípusa webhook-végpontokon keresztül kerül kézbesítésre. A hat hívás-életciklus esemény (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) szintén elküldésre kerül az örökölt, egy URL-es webhooknak — ha örökölt URL-je és egyező végpontja is van, az eseményt mindkét útvonalon megkapja. A blokkoló működés (a telephony.incoming / web.incoming konfigurációs adatcsere és a webhook módú eszközdiszpécselés) kizárólag az örökölt útvonalon érhető el; minden végpontkézbesítés azonnali visszajelzés nélküli értesítés.

Payload formátuma

A végpontkézbesítések egy data, event_id és type mezőket tartalmazó JSON-objektumok:
Az event_id minden kibocsátott eseményhez egyedi. Azonos az újrapróbálkozások során és minden olyan végponton, amely megkapja az eseményt — ezt használja deduplikálásra. Az örökölt, egy URL-es webhook ugyanazt a type és data mezőt küldi, de event_id nélkül:
Az átvitel során minden törzs kanonikus formában szerializálódik — a kulcsok betűrendbe vannak rendezve, nincs üres karakter, a kódolás pedig UTF-8. A dokumentációban szereplő formázott példák kizárólag az olvashatóságot szolgálják. Az eseménytípusok és payloadmezők teljes listájáért tekintse meg az Eseménykatalógust.

Aláírás ellenőrzése

Minden kérés a nyers kéréstörzs feletti HMAC-SHA256-aláírást tartalmazza az X-ThunderPhone-Signature fejlécben. Az aláírókulcs a végpont secret értéke (vagy örökölt kézbesítések esetén a szervezeti szintű webhook secret értéke).

Lépések

  1. Olvassa be a nyers kéréstörzset minden feldolgozás előtt.
  2. Számítsa ki: hmac_sha256(secret, body).hexdigest().
  3. Hasonlítsa össze konstans időben az X-ThunderPhone-Signature fejléc értékével.
Pontosan azokat a bájtokat írjuk alá, amelyeket továbbítunk, és ezek a bájtok a kanonikus JSON-szerializálást alkotják (rendezett kulcsok, tömör elválasztók). Ezért a nyers törzs ellenőrzése mindig működik — és ha a keretrendszere csak feldolgozott JSON-t ad át, annak rendezett kulcsokkal és tömör elválasztókkal történő újraszerializálása azonos bájtokat eredményez. Mindkét eljárást ismerteti az ellenőrzési útmutató.

Kézbesítési szemantika

Ezek a szemantikák a végpontokra történő kézbesítésekre vonatkoznak. A régi, egyetlen URL-es webhook egyetlen szinkron kísérletből áll, újrapróbálkozások nélkül.
Minden eseményt azonnal egyszer megkísérlünk kézbesíteni. Bármely 2xx válasz visszaigazolja a kézbesítést. Minden más esetben (nem 2xx, kapcsolati hiba, időtúllépés) az első kísérlet után 1 perccel, 5 perccel, 30 perccel, 2 órával, 6 órával, 12 órával és 24 órával újrapróbáljuk — ez 8 kísérletet jelent 24 óra alatt. Ha minden kísérlet sikertelen, a kézbesítés leáll, és a végpont status="failing" jelölést kap a webhook-végpontokban. Amint az adattartalmat tartósan fogadta, adjon vissza 2xx választ; a feldolgozást aszinkron módon végezze.
A kézbesítési sorrend legjobb szándék szerinti. A gyakorlatban az eseményeket a kibocsátásuk sorrendjében kézbesítjük, de hiba esetén az újrapróbálkozások megváltoztathatják a sorrendet. Mindig szüntesse meg a duplikációkat, és egyeztesse az adatokat call_id / objektumazonosító alapján.
A kézbesítés legalább egyszeri: egy olyan válasz utáni újrapróbálkozás, amelyet nem észleltünk, megduplázhat egy eseményt. Minden újrapróbálkozás ugyanazt az event_id azonosítót tartalmazza, ezért tárolja a feldolgozott azonosítókat, és hagyja ki az ismétlődéseket. Az event_id a végpontok között is közös — két, ugyanarra az eseményre feliratkozott végpont ugyanazt az event_id azonosítót kapja.
A végpontokra történő kézbesítések kísérletenként 30 mp időtúllépéssel rendelkeznek. A régi útvonalon az élő hívások működését vezérlő blokkoló kérések — a telephony.incoming / web.incoming konfigurációs adatcsere — 10 mp után időtúllépéssel leállnak, de a lassú válasz késlelteti a hívás fogadását, ezért törekedjen arra, hogy néhány másodpercen belül válaszoljon. A webhook módú eszközhívás 20 mp-et engedélyez.
A kimenő webhookok a ThunderPhone felhőalapú IP-címtartományából származnak. Ha a tűzfal engedélyezési listát igényel, lépjen kapcsolatba az ügyfélszolgálattal, és megosztjuk az aktuális tartományokat.

Választás a régi és a végpont-alapú webhookok között

Az új integrációknak végpont-alapú webhookokon keresztül kell eseményeket fogadniuk. Csak akkor tartson meg (vagy adjon hozzá) régi URL-t, ha a hívásokat a fogadás időpontjában dinamikusan konfigurálja, vagy webhook módú eszközhívást használ — ezek a kérés/válasz adatcserék csak a régi útvonalon futnak.

Kapcsolódó témák

Eseménykatalógus

Az összes eseménytípus és adattartalmuk.

Webhook-végpontok

Több végpont, eseményszűrő és titkos kulcs kezelése.

telephony.incoming / web.incoming

A blokkoló kérés, amelyre a szerverének a hívások konfigurálásához válaszolnia kell.

telephony.complete / web.complete

Hívás utáni adattartalom átirattal, felvétellel és mérőszámokkal.