Skip to main content
ThunderPhone sender HTTP-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.
Alle ti hændelsestyper i hændelseskataloget leveres via webhook-slutpunkter. De seks opkaldslivscyklus-hændelser (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 med data, 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:
Under overførsel serialiseres hver body kanonisk — nøgler sorteres alfabetisk, ingen mellemrum, UTF-8. De pænt formaterede eksempler i denne dokumentation er kun for læsbarhed. Se hændelseskataloget for den fulde liste over hændelses- typer og payloadfelter.

Signaturverificering

Hver anmodning indeholder en HMAC-SHA256-signatur over den rå anmodnings- body i headeren X-ThunderPhone-Signature. Signeringsnøglen er endpointets secret (eller din organisations webhook-secret for ældre leveringer).

Trin

  1. Læs den rå anmodnings-body før enhver parsing.
  2. Beregn hmac_sha256(secret, body).hexdigest().
  3. Sammenlign i konstant tid med headeren X-ThunderPhone-Signature.
Vi signerer præcis de bytes, vi sender, og disse bytes er den kanoniske JSON-serialisering (sorterede nøgler, kompakte separatorer). Derfor virker verificering mod den rå body altid — og hvis dit framework kun giver dig parset JSON, producerer genserialisering med sorterede nøgler og kompakte separatorer identiske bytes. Begge fremgangsmåder er beskrevet i verificeringsvejledningen.

Leveringssemantik

Denne semantik gælder for leveringer til endepunkter. Den ældre webhook med én URL er ét enkelt synkront forsøg uden 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.
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.
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.
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.
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.