Skip to main content
ThunderPhone sendet HTTP-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.
Alle zehn Ereignistypen im Ereigniskatalog werden über Webhook-Endpunkte zugestellt. Die sechs Ereignisse des Anruflebenszyklus (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 mit data, 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:
Bei der Übertragung wird jeder Body kanonisch serialisiert — Schlüssel alphabetisch sortiert, ohne Leerraum, UTF-8. Die formatierten Beispiele in diesen Docs dienen nur der Lesbarkeit. Im Ereigniskatalog finden Sie die vollständige Liste der Ereignistypen und Payload-Felder.

Signaturprüfung

Jede Anfrage enthält im Header X-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

  1. Lesen Sie den rohen Anfrage-Body vor jeder Verarbeitung.
  2. Berechnen Sie hmac_sha256(secret, body).hexdigest().
  3. Vergleichen Sie das Ergebnis in konstanter Zeit mit dem Header X-ThunderPhone-Signature.
Wir signieren exakt die Bytes, die wir übertragen. Diese Bytes sind die kanonische JSON-Serialisierung (sortierte Schlüssel, kompakte Trennzeichen). Daher funktioniert die Prüfung anhand des rohen Bodys immer — und wenn Ihr Framework Ihnen nur geparstes JSON bereitstellt, erzeugt eine erneute Serialisierung mit sortierten Schlüsseln und kompakten Trennzeichen identische Bytes. Beide Vorgehensweisen werden im Leitfaden zur Signaturprüfung behandelt.

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.
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.
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.
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.
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.
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.