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.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 meddata, 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:
Signaturverifisering
Hver forespørsel har en HMAC-SHA256-signatur over den rå forespørselsbrødteksten iX-ThunderPhone-Signature-headeren. Signeringsnøkkelen er
endepunktets secret (eller organisasjonens webhook-secret for eldre
leveringer).
Trinn
- Les den rå forespørselsbrødteksten før eventuell parsing.
- Beregn
hmac_sha256(secret, body).hexdigest(). - Sammenlign i konstant tid med
X-ThunderPhone-Signature-headeren.
Leveringssemantikk
Disse semantikkene gjelder leveringer til endepunkter. Den eldre webhooken med én URL er ett enkelt synkront forsøk uten nye forsøk.Nye forsøk
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.Rekkefølge
Rekkefølge
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.Duplikater
Duplikater
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.Tidsavbrudd
Tidsavbrudd
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.Kilde-IP-adresser
Kilde-IP-adresser
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.