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.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 egydata, event_id és type mezőket tartalmazó
JSON-objektumok:
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:
Aláírás ellenőrzése
Minden kérés a nyers kéréstörzs feletti HMAC-SHA256-aláírást tartalmazza azX-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
- Olvassa be a nyers kéréstörzset minden feldolgozás előtt.
- Számítsa ki:
hmac_sha256(secret, body).hexdigest(). - Hasonlítsa össze konstans időben az
X-ThunderPhone-Signaturefejléc értékével.
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.Újrapróbálkozások
Újrapróbálkozások
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.Sorrendiség
Sorrendiség
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.Duplikátumok
Duplikátumok
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.Időtúllépések
Időtúllépések
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.Forrás IP-címek
Forrás IP-címek
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.