POST-anmodninger til din server, når der sker noget under et opkald — et indgående opkald starter, et opkald slutter, en vurderingskørsel fuldføres, en advarsel udløses osv. Der er to leveringsmodeller:
Webhook-slutpunkter (anbefalet)
Flere URL’er, hemmeligheder pr. slutpunkt, hændelsesfiltre pr. slutpunkt
og automatiske genforsøg.
Administrer via
GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.Forældet webhook med én URL
Én URL pr. organisation. Indeholder opkaldslivscyklus-hændelserne, herunder de
blokerende konfigurationsudvekslinger. Administreres via
GET/PUT /v1/webhook.telephony.incoming, telephony.complete, telephony.tool,
web.incoming, web.complete, web.tool) sendes også til det
forældede webhook med én URL — hvis du både har en forældet URL og et
matchende slutpunkt, modtager du hændelsen på begge stier. Blokerende
adfærd (telephony.incoming / web.incoming-konfigurationsudvekslingen
og værktøjsafsendelse i webhooktilstand)
findes udelukkende på den forældede sti; hver levering til et slutpunkt er en
send-og-glem-notifikation.
Payloadformat
Leveringer til slutpunkter er et JSON-objekt meddata, event_id og
type:
event_id er unik for hver udsendt hændelse. Den er identisk på tværs af genforsøg
og på tværs af hvert slutpunkt, der modtager hændelsen — dedupliker ud fra den.
Det forældede webhook med én URL sender samme type og data, men
uden event_id:
Signaturverificering
Hver anmodning indeholder en HMAC-SHA256-signatur over den rå anmodnings- body i headerenX-ThunderPhone-Signature. Signeringsnøglen er
endpointets secret (eller din organisations webhook-secret for
ældre leveringer).
Trin
- Læs den rå anmodnings-body før enhver parsing.
- Beregn
hmac_sha256(secret, body).hexdigest(). - Sammenlign i konstant tid med headeren
X-ThunderPhone-Signature.
Leveringssemantik
Denne semantik gælder for leveringer til endepunkter. Den ældre webhook med én URL er ét enkelt synkront forsøg uden genforsøg.Genforsøg
Genforsøg
Hver hændelse forsøges leveret én gang med det samme. Ethvert
2xx-svar
bekræfter leveringen. Ved ethvert andet resultat (ikke-2xx,
forbindelsesfejl, timeout) forsøger vi igen 1 min., 5 min., 30 min., 2 t., 6 t.,
12 t. og 24 t. efter det første forsøg — 8 forsøg fordelt over
24 timer. Hvis alle forsøg mislykkes, stopper leveringen, og endepunktet
markeres med status="failing" i
webhook-endepunkter. Returner 2xx, så snart
payloadet er varigt accepteret; behandl det asynkront.Rækkefølge
Rækkefølge
Leveringsrækkefølgen er best effort. I praksis leverer vi i den
rækkefølge, hændelser udsendes, men genforsøg kan ændre rækkefølgen ved fejl.
Dedupliker og afstem altid efter
call_id / objekt-id.Dubletter
Dubletter
Levering er mindst én gang: et genforsøg efter et svar, vi aldrig
modtog, kan duplikere en hændelse. Hvert genforsøg indeholder samme
event_id, så gem behandlede id’er, og spring gentagelser over. event_id deles
også på tværs af endepunkter — to endepunkter, der abonnerer på den
samme hændelse, modtager den samme event_id.Tidsgrænser
Tidsgrænser
Leveringer til endepunkter har en tidsgrænse på 30 sek. pr. forsøg. På den
ældre sti har blokerende anmodninger, der styrer aktive opkald — den
telephony.incoming / web.incoming
konfigurationsudveksling — en tidsgrænse på 10 sek., men et langsomt
svar forsinker besvarelsen af opkaldet, så sigt efter at svare inden for et par
sekunder. Værktøjsafsendelse i webhooktilstand tillader 20 sek.Kilde-IP'er
Kilde-IP'er
Udgående webhooks kommer fra ThunderPhones cloud-IP-område.
Hvis din firewall kræver en tilladelsesliste, skal du kontakte support, så
deler vi de aktuelle områder.
Valg mellem ældre og endepunktbaserede webhooks
Nye integrationer bør modtage hændelser via endepunktbaserede
webhooks. Behold (eller tilføj) kun en ældre URL, hvis du konfigurerer opkald
dynamisk på tidspunktet for besvarelse eller bruger værktøjsafsendelse i webhooktilstand — disse
anmodnings-/svarudvekslinger kører kun på den ældre sti.
Relateret
Hændelseskatalog
Alle hændelsestyper og deres payloads.
Webhook-endepunkter
Administrer flere endepunkter, hændelsesfiltre og hemmeligheder.
telephony.incoming / web.incoming
Den blokerende anmodning, som din server skal besvare for at konfigurere opkald.
telephony.complete / web.complete
Payload efter opkaldet med transskription, optagelse og målinger.