Skip to main content
ThunderPhone lähettää HTTP-POST-pyyntöjä palvelimellesi, kun puhelun aikana tapahtuu jotain — saapuva puhelu alkaa, puhelu päättyy, arviointiajo valmistuu, hälytys laukeaa ja niin edelleen. Toimitusmalleja on kaksi:

Webhook-päätepisteet (suositellaan)

Useita URL-osoitteita, päätepistekohtaiset salaisuudet, päätepistekohtaiset tapahtumasuodattimet ja automaattiset uudelleenyritykset. Hallitse kohdan GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints kautta.

Yhden URL:n vanha webhook

Yksi URL-osoite organisaatiota kohden. Sisältää puhelun elinkaaren tapahtumat, mukaan lukien estävät määritysvaihdot. Hallitaan kohdassa GET/PUT /v1/webhook.
Kaikki kymmenen tapahtumaluettelon tapahtumatyyppiä toimitetaan webhook-päätepisteiden kautta. Kuusi puhelun elinkaaren tapahtumaa (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) lähetetään myös vanhaan yhden URL:n webhookiin — jos sinulla on sekä vanha URL että vastaava päätepiste, vastaanotat tapahtuman molempia reittejä pitkin. Estävä toiminta (telephony.incoming- ja web.incoming-määritysvaihto ja webhook-tilan työkalun välitys) on käytettävissä vain vanhalla reitillä; jokainen päätepistetoimitus on ei-estävä ilmoitus.

Hyötykuorman muoto

Päätepistetoimitukset ovat JSON-objekteja, joissa ovat data, event_id ja type:
event_id on yksilöllinen jokaiselle lähetetylle tapahtumalle. Se on sama sekä uudelleenyrityksissä että kaikissa tapahtuman vastaanottavissa päätepisteissä — käytä sitä duplikaattien poistoon. Vanha yhden URL:n webhook lähettää saman type- ja data-sisällön mutta ilman event_id-arvoa:
Verkossa jokainen runko serialisoidaan kanonisesti — avaimet lajitellaan aakkosjärjestykseen, välilyöntejä ei käytetä ja merkistö on UTF-8. Näiden dokumenttien muotoillut esimerkit ovat vain luettavuuden vuoksi. Katso tapahtumaluettelosta tapahtumatyyppien ja hyötykuormakenttien täydellinen luettelo.

Allekirjoituksen vahvistaminen

Jokainen pyyntö sisältää HMAC-SHA256-allekirjoituksen raakapyynnön rungosta X-ThunderPhone-Signature-otsakkeessa. Allekirjoitusavain on päätepisteen secret (tai organisaatiotason webhookin secret vanhoille toimituksille).

Vaiheet

  1. Lue raakapyynnön runko ennen mitään jäsentämistä.
  2. Laske hmac_sha256(secret, body).hexdigest().
  3. Vertaa sitä vakioaikaisesti X-ThunderPhone-Signature-otsakkeeseen.
Allekirjoitamme täsmälleen lähettämämme tavut, ja nämä tavut ovat kanoninen JSON-sarjoitus (lajitellut avaimet, tiiviit erottimet). Siksi raakapyyntöön perustuva vahvistus toimii aina — ja jos kehys antaa sinulle vain jäsennetyn JSONin, sen uudelleensarjoittaminen lajitelluilla avaimilla ja tiiviillä erottimilla tuottaa samat tavut. Molemmat menetelmät on kuvattu vahvistusoppaassa.

Toimitussemantiikka

Nämä semantiikat koskevat päätepisteisiin tehtäviä toimituksia. Vanha yhden URL-osoitteen webhook on yksi synkroninen yritys ilman uudelleenyrityksiä.
Jokaista tapahtumaa yritetään toimittaa kerran välittömästi. Mikä tahansa 2xx-vastaus vahvistaa toimituksen. Kaikissa muissa tilanteissa (muu kuin 2xx-vastaus, yhteysvirhe, aikakatkaisu) yritämme uudelleen 1 min, 5 min, 30 min, 2 h, 6 h, 12 h ja 24 h ensimmäisen yrityksen jälkeen — 8 yritystä 24 tunnin aikana. Jos jokainen yritys epäonnistuu, toimitus pysähtyy ja päätepiste merkitään tilaan status="failing" kohdassa webhook-päätepisteet. Palauta 2xx heti, kun hyötykuorma on vastaanotettu pysyvästi; käsittele se asynkronisesti.
Toimitusjärjestys on parhaaseen pyrkivä. Käytännössä toimitamme tapahtumat siinä järjestyksessä kuin ne lähetetään, mutta uudelleenyritykset voivat muuttaa järjestystä epäonnistumisen yhteydessä. Deduplikoi ja täsmäytä aina call_id- / objektitunnuksen perusteella.
Toimitus on vähintään kerran -tyyppinen: uudelleenyritys vastauksen jälkeen, jota emme koskaan nähneet, voi tuottaa tapahtumasta kaksoiskappaleen. Jokaisessa uudelleenyrityksessä on sama event_id, joten tallenna käsitellyt tunnukset ja ohita toistot. event_id on myös yhteinen päätepisteiden välillä — kaksi samaa tapahtumaa tilaavaa päätepistettä vastaanottaa saman event_id:n.
Päätepistetoimituksissa on 30 s:n aikakatkaisu yritystä kohden. Vanhassa polussa estävät pyynnöt, jotka ohjaavat aktiivisen puhelun toimintaa — telephony.incoming / web.incoming -määritysvaihto — aikakatkaistaan 10 s jälkeen, mutta hidas vastaus viivästyttää puheluun vastaamista, joten pyri vastaamaan muutamassa sekunnissa. Webhook-tilan työkalujen välitys sallii 20 s.
Lähtevät webhookit tulevat ThunderPhonen pilven IP-osoitealueelta. Jos palomuurisi edellyttää sallittujen osoitteiden luetteloa, ota yhteyttä tukeen, niin jaamme nykyiset alueet.

Valinta vanhojen ja päätepistepohjaisten webhookien välillä

Uusien integraatioiden tulee vastaanottaa tapahtumia päätepistepohjaisten webhookien kautta. Pidä (tai lisää) vanha URL-osoite vain, jos määrität puhelut dynaamisesti puheluun vastaamisen yhteydessä tai käytät webhook-tilan työkalujen välitystä — nämä pyyntö/vastausvaihdot toimivat vain vanhassa polussa.

Aiheeseen liittyvää

Tapahtumaluettelo

Kaikki tapahtumatyypit ja niiden hyötykuormat.

Webhook-päätepisteet

Hallitse useita päätepisteitä, tapahtumasuodattimia ja salaisuuksia.

telephony.incoming / web.incoming

Estävä pyyntö, johon palvelimesi on vastattava puheluiden määrittämiseksi.

telephony.complete / web.complete

Puhelun jälkeinen hyötykuorma, joka sisältää litteroinnin, tallenteen ja mittarit.