Skip to main content
ThunderPhone sender HTTP-POST-forespørsler til serveren din når ting skjer under en samtale — et innkommende anrop starter, et anrop avsluttes, en vurderingskjøring fullføres, et varsel utløses og så videre. Det finnes to leveringsmodeller:

Webhook-endepunkter (anbefalt)

Flere URL-er, hemmeligheter per endepunkt, hendelsesfiltre per endepunkt og automatiske nye forsøk. Administrer via GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.

Eldre webhook med én URL

Én URL per organisasjon. Inneholder hendelsene i anropets livssyklus, inkludert de blokkerende konfigurasjonsutvekslingene. Administreres på GET/PUT /v1/webhook.
Alle de ti hendelsestypene i hendelseskatalogen leveres gjennom webhook-endepunkter. De seks hendelsene i anropets livssyklus (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) sendes også til den eldre webhooken med én URL — hvis du har både en eldre URL og et samsvarende endepunkt, mottar du hendelsen på begge banene. Blokkerende atferd (konfigurasjonsutvekslingen for telephony.incoming / web.incoming og verktøyskøyring i webhook-modus) finnes utelukkende på den eldre banen; hver levering til et endepunkt er et fire-and-forget-varsel.

Nyttelastformat

Leveringer til endepunkter er et JSON-objekt med data, event_id og type:
event_id er unik for hver utløste hendelse. Den er identisk på tvers av nye forsøk og på tvers av hvert endepunkt som mottar hendelsen — bruk den til deduplisering. Den eldre webhooken med én URL sender samme type og data, men uten event_id:
Ved overføring serialiseres hver body kanonisk — nøkler sortert alfabetisk, uten mellomrom, UTF-8. De pent formaterte eksemplene i denne dokumentasjonen er kun for lesbarhet. Se hendelseskatalogen for hele listen over hendelses- typer og nyttelastfelt.

Signaturverifisering

Hver forespørsel har en HMAC-SHA256-signatur over den rå forespørselsbrødteksten i X-ThunderPhone-Signature-headeren. Signeringsnøkkelen er endepunktets secret (eller organisasjonens webhook-secret for eldre leveringer).

Trinn

  1. Les den rå forespørselsbrødteksten før eventuell parsing.
  2. Beregn hmac_sha256(secret, body).hexdigest().
  3. Sammenlign i konstant tid med X-ThunderPhone-Signature-headeren.
Vi signerer nøyaktig byteene vi sender, og disse byteene er den kanoniske JSON-serialiseringen (sorterte nøkler, kompakte skilletegn). Derfor fungerer verifisering mot den rå brødteksten alltid — og hvis rammeverket ditt bare gir deg parsede JSON-data, produserer reserialisering med sorterte nøkler og kompakte skilletegn identiske byte. Begge fremgangsmåtene er beskrevet i verifiseringsveiledningen.

Leveringssemantikk

Disse semantikkene gjelder leveringer til endepunkter. Den eldre webhooken med én URL er ett enkelt synkront forsøk uten nye forsøk.
Hver hendelse forsøkes levert én gang umiddelbart. Ethvert 2xx-svar bekrefter leveringen. Ved ethvert annet utfall (ikke-2xx, tilkoblingsfeil, tidsavbrudd) forsøker vi på nytt 1 min, 5 min, 30 min, 2 t, 6 t, 12 t og 24 t etter første forsøk — 8 forsøk over 24 timer. Hvis hvert forsøk mislykkes, stopper leveringen, og endepunktet merkes med status="failing" i webhook-endepunkter. Returner 2xx så snart nyttelasten er varig akseptert; behandle den asynkront.
Leveringsrekkefølge er basert på beste innsats. I praksis leverer vi i rekkefølgen hendelsene sendes ut, men nye forsøk kan endre rekkefølgen ved feil. Fjern alltid duplikater og avstem etter call_id / objekt-id.
Levering er minst én gang: et nytt forsøk etter et svar vi aldri mottok, kan duplisere en hendelse. Hvert nye forsøk har samme event_id, så lagre behandlede id-er og hopp over gjentakelser. event_id er også delt på tvers av endepunkter — to endepunkter som abonnerer på den samme hendelsen, mottar samme event_id.
Leveringer til endepunkter har et tidsavbrudd på 30 s per forsøk. På den eldre banen får blokkerende forespørsler som styrer atferd under aktive samtaler — utvekslingen av konfigurasjon for telephony.incoming / web.incoming — tidsavbrudd etter 10 s, men et tregt svar forsinker besvaring av samtalen, så prøv å svare innen et par sekunder. Verktøyutsending i webhook-modus tillater 20 s.
Utgående webhooks kommer fra ThunderPhones sky-IP-område. Hvis brannmuren din krever en tillatelsesliste, kontakt kundestøtte, så deler vi de gjeldende områdene.

Velge mellom eldre og endepunktbaserte webhooks

Nye integrasjoner bør konsumere hendelser via endepunktbaserte webhooks. Behold (eller legg til) en eldre URL bare hvis du konfigurerer samtaler dynamisk når de besvares, eller bruker verktøyutsending i webhook-modus — disse forespørsel-/svarutvekslingene kjører kun på den eldre banen.

Relatert

Hendelseskatalog

Alle hendelsestyper og nyttelastene deres.

Webhook-endepunkter

Administrer flere endepunkter, hendelsesfiltre og hemmeligheter.

telephony.incoming / web.incoming

Den blokkerende forespørselen serveren din må svare på for å konfigurere samtaler.

telephony.complete / web.complete

Nyttelast etter samtalen med transkripsjon, opptak og måltall.