POST-Anfragen an Ihren Server, wenn während eines Anrufs Ereignisse
auftreten — ein eingehender Anruf beginnt, ein Anruf endet, ein Bewertungsdurchlauf
abgeschlossen wird, eine Warnung ausgelöst wird usw. Es gibt zwei Zustellmodelle:
Webhook-Endpunkte (empfohlen)
Mehrere URLs, Secrets pro Endpunkt, Ereignisfilter pro Endpunkt
und automatische Wiederholungsversuche.
Verwaltung über
GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.Legacy-Webhook mit einzelner URL
Eine URL pro Organisation. Enthält die Ereignisse des Anruflebenszyklus, einschließlich der
blockierenden Konfigurationsaustausche. Verwaltung über
GET/PUT /v1/webhook.telephony.incoming, telephony.complete, telephony.tool,
web.incoming, web.complete, web.tool) werden zusätzlich an den
Legacy-Webhook mit einzelner URL gesendet — wenn Sie sowohl eine Legacy-URL als auch einen
passenden Endpunkt haben, erhalten Sie das Ereignis über beide Pfade. Das blockierende
Verhalten (der telephony.incoming- / web.incoming-Konfigurationsaustausch
und der Tool-Versand im Webhook-Modus) ist
ausschließlich auf dem Legacy-Pfad verfügbar; jede Zustellung an einen Endpunkt ist eine
Fire-and-Forget-Benachrichtigung.
Payload-Format
Endpunktzustellungen sind ein JSON-Objekt mitdata, event_id und
type:
event_id ist für jedes ausgegebene Ereignis eindeutig. Sie ist bei Wiederholungsversuchen
und über jeden Endpunkt hinweg, der das Ereignis empfängt, identisch — verwenden Sie sie zur Deduplizierung.
Der Legacy-Webhook mit einzelner URL sendet denselben type und dieselben data, jedoch
ohne event_id:
Signaturprüfung
Jede Anfrage enthält im HeaderX-ThunderPhone-Signature eine HMAC-SHA256-Signatur über den rohen Anfrage-Body. Der Signaturschlüssel ist das secret des Endpunkts (oder Ihr Webhook-secret auf Organisationsebene für Legacy-Zustellungen).
Schritte
- Lesen Sie den rohen Anfrage-Body vor jeder Verarbeitung.
- Berechnen Sie
hmac_sha256(secret, body).hexdigest(). - Vergleichen Sie das Ergebnis in konstanter Zeit mit dem Header
X-ThunderPhone-Signature.
Zustellungssemantik
Diese Semantik gilt für Zustellungen an Endpunkte. Der ältere Webhook mit einer einzelnen URL führt einen einzelnen synchronen Versuch ohne Wiederholungen aus.Wiederholungen
Wiederholungen
Jedes Ereignis wird sofort einmal zugestellt. Jede
2xx-Antwort
bestätigt die Zustellung. Bei jedem anderen Ergebnis (kein 2xx,
Verbindungsfehler, Zeitüberschreitung) wiederholen wir den Versuch
1 m, 5 m, 30 m, 2 h, 6 h, 12 h und 24 h nach dem ersten Versuch —
8 Versuche über 24 Stunden. Wenn jeder Versuch fehlschlägt, wird die
Zustellung beendet und der Endpunkt in
Webhook-Endpunkten mit status="failing"
markiert. Geben Sie 2xx zurück, sobald die Nutzlast dauerhaft
angenommen wurde; verarbeiten Sie sie asynchron.Reihenfolge
Reihenfolge
Die Zustellungsreihenfolge erfolgt nach bestem Bemühen. In der Praxis
stellen wir Ereignisse in der Reihenfolge zu, in der sie ausgegeben
werden, aber Wiederholungen können bei Fehlern die Reihenfolge ändern.
Deduplizieren Sie immer und gleichen Sie anhand von
call_id /
Objekt-ID ab.Duplikate
Duplikate
Die Zustellung erfolgt mindestens einmal: Eine Wiederholung nach
einer Antwort, die wir nie gesehen haben, kann ein Ereignis duplizieren.
Jede Wiederholung enthält dieselbe
event_id; speichern Sie daher
verarbeitete IDs und überspringen Sie Wiederholungen. event_id wird
auch zwischen Endpunkten geteilt — zwei Endpunkte, die dasselbe Ereignis
abonniert haben, erhalten dieselbe event_id.Zeitüberschreitungen
Zeitüberschreitungen
Endpunkt-Zustellungen haben pro Versuch eine Zeitüberschreitung von
30 s. Im älteren Pfad werden blockierende Anfragen, die das
Verhalten aktiver Anrufe steuern — der
Konfigurationsaustausch
telephony.incoming / web.incoming —
nach 10 s abgebrochen. Eine langsame Antwort verzögert jedoch die
Annahme des Anrufs, daher sollten Sie innerhalb weniger Sekunden
antworten. Tool-Dispatch im Webhook-Modus erlaubt 20 s.Quell-IP-Adressen
Quell-IP-Adressen
Ausgehende Webhooks stammen aus dem Cloud-IP-Bereich von ThunderPhone.
Wenn Ihre Firewall eine Zulassungsliste erfordert, kontaktieren Sie den
Support, und wir teilen Ihnen die aktuellen Bereiche mit.
Auswahl zwischen älteren und endpunktbasierten Webhooks
Neue Integrationen sollten Ereignisse über endpunktbasierte Webhooks
verarbeiten. Behalten Sie eine ältere URL nur bei (oder fügen Sie eine
hinzu), wenn Sie Anrufe bei der Annahme dynamisch konfigurieren oder
Tool-Dispatch im Webhook-Modus verwenden — diese Anfrage-/Antwort-
Austausche laufen nur über den älteren Pfad.
Verwandte Inhalte
Ereigniskatalog
Alle Ereignistypen und ihre Nutzlasten.
Webhook-Endpunkte
Verwalten Sie mehrere Endpunkte, Ereignisfilter und Secrets.
telephony.incoming / web.incoming
Die blockierende Anfrage, die Ihr Server zur Konfiguration von Anrufen beantworten muss.
telephony.complete / web.complete
Nutzlast nach dem Anruf mit Transkript, Aufzeichnung und Metriken.