Webhook-Endpunkte

Das endpointbasierte Webhook-System ermöglicht Ihnen, mehrere Ziele pro Organisation zu registrieren, jeweils mit eigenem Secret, eigenem Status und eigenem Abonnement für eine Teilmenge von Ereignistypen. Dies ist das empfohlene Modell für alle neuen Integrationen. Vergleichen Sie dies mit dem veralteten Single-URL-Webhook, der aus Gründen der Abwärtskompatibilität beibehalten wird, aber nur eine URL pro Organisation unterstützt.

Endpunkte

Methode	Pfad	Erforderliche Rolle	Beschreibung
`GET`	`/v1/developer/webhook-endpoints`	`admin+`	Endpunkte auflisten
`POST`	`/v1/developer/webhook-endpoints`	`admin+`	Einen Endpunkt erstellen
`PATCH`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Bezeichnung / URL / Ereignisse / Status aktualisieren
`DELETE`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Einen Endpunkt löschen
`POST`	`/v1/developer/webhook-endpoints/{endpoint_id}/test`	`admin+`	Eine signierte Testzustellung senden

Endpunktobjekt

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

Feld	Typ	Beschreibung
`id`	UUID	Endpunkt-ID
`label`	string	Anzeigename, 1–120 Zeichen
`url`	string	HTTPS-URL; `http://localhost` für die Entwicklung zulässig
`events`	array of string	Abonnierte Ereignistypen (siehe gültige Werte). Ein leeres Array abonniert alle Ereignisse
`status`	string	`active`, `disabled` (manuell pausiert) oder `failing` (automatisch gesetzt, wenn eine Zustellung ihren 24-Stunden-Wiederholungsplan ohne ein einziges 2xx ausschöpft)
`secret_hint`	string	Die ersten 4 und letzten 4 Zeichen des Signatur-Secrets mit Auslassungszeichen (`a1b2…9f0e`) — ausreichend, um es mit dem lokal gespeicherten Secret abzugleichen, ohne den vollständigen Wert offenzulegen
`created_at`, `updated_at`	timestamp

Das vollständige secret des Endpunkts wird bei der Erstellung einmal zurückgegeben und danach nie wieder. Speichern Sie es sicher — falls Sie es verlieren, löschen Sie den Endpunkt und erstellen Sie ihn erneut.

Gültige Ereignistypen

events wird anhand genau dieser Menge validiert — Werte außerhalb der Liste geben 400 zurück. Unter Ereigniskatalog finden Sie die Payload-Struktur jedes Typs.

telephony.incoming, telephony.complete, telephony.tool
web.incoming, web.complete, web.tool
call.graded
issue.reported
test-call.completed
alert.triggered

Endpunktstatus

active — Zustellungen werden normal ausgeführt.
disabled — manuell über PATCH pausiert. Es werden keine Anfragen gesendet. Den Status eines disabled-Endpunkts ändern wir niemals; die Rücksetzung auf active liegt immer bei Ihnen.
failing — wird automatisch gesetzt, wenn eine Zustellung an den Endpunkt ihren gesamten Wiederholungsplan ausschöpft (8 Versuche innerhalb von 24 Stunden), ohne jemals ein 2xx zu erhalten. Ein fehlerhafter Endpunkt erhält keinen weiteren Traffic. Sobald der Endpunkt korrigiert ist, setzen Sie seinen Status per PATCH wieder auf active; Zustellungen, deren Wiederholungsplan noch nicht abgelaufen ist, werden an der Stelle fortgesetzt, an der sie unterbrochen wurden.

Endpunkte auflisten

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Gibt ein Array von Endpunktobjekten zurück.

Endpunkt erstellen

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]

Anfragefelder

Feld	Typ	Erforderlich	Beschreibung
`label`	string	ja	1–120 Zeichen
`url`	string	ja	HTTPS-URL (`http` nur für `localhost` / `127.0.0.1` zulässig)
`events`	array	nein	Leer/ausgelassen abonniert alle Ereignisse. Es müssen die unter Gültige Ereignistypen aufgeführten Werte verwendet werden; Duplikate werden entfernt

Gibt 201 Created mit dem Endpunktobjekt sowie einem zusätzlichen secret-Feld der obersten Ebene zurück, das den rohen Signaturschlüssel enthält — eine 48 Zeichen lange Hexadezimalzeichenfolge:

{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}

secret wird nur bei der Erstellung zurückgegeben. Nachfolgende GET-Antworten enthalten nur secret_hint. Kopieren Sie den vollständigen Wert in Ihren Secret Manager, bevor Sie die Antwort verwerfen.

Endpunkt aktualisieren

curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'

Feld	Typ	Beschreibung
`label`	string
`url`	string
`events`	array
`status`	string	`active` oder `disabled`. Setzen Sie `active`, um einen Endpunkt wieder zu aktivieren, den der Server als `failing` markiert hat

Gibt 200 OK mit dem aktualisierten Endpunktobjekt zurück.

Testzustellung senden

Senden Sie ein synthetisches webhook.test-Ereignis über die normale Zustellungspipeline an einen Endpunkt, einschließlich kanonischer JSON-Serialisierung, X-ThunderPhone-Signature, Zustellungsaufzeichnung und Verwaltung von Wiederholungsversuchen. Der Test richtet sich unabhängig von seinem events-Filter an den ausgewählten Endpunkt.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Der Endpunkt empfängt einen Umschlag wie diesen:

{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}

Die API gibt nach dem ersten Versuch 200 OK zurück, auch wenn das Ziel einen Fehler zurückgibt. Prüfen Sie success, status, response_code und error auf das Ergebnis der Zustellung:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test ist synthetisch und kann nicht zum events-Abonnement eines Endpunkts hinzugefügt werden. Wenn der erste Versuch fehlschlägt, folgt die Zustellung demselben Wiederholungszeitplan wie normale Ereigniszustellungen.

Einen Endpunkt löschen

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Gibt 204 No Content zurück. Die Zustellung an die URL wird sofort beendet; laufende Wiederholungsversuche werden abgebrochen.

Ereigniskatalog

Die vollständige Liste der events-Werte, die Sie abonnieren können.

Webhooks-Übersicht

Signaturprüfung und Zustellungssemantik.

Webhooks

Function Tools

Endpunkte

Endpunktobjekt

Gültige Ereignistypen

Endpunktstatus

Endpunkte auflisten

Endpunkt erstellen

Anfragefelder

Endpunkt aktualisieren

Testzustellung senden

Einen Endpunkt löschen

Verwandte Themen

Ereigniskatalog

Webhooks-Übersicht

​Endpunkte

​Endpunktobjekt

​Gültige Ereignistypen

​Endpunktstatus

​Endpunkte auflisten

​Endpunkt erstellen

​Anfragefelder

​Endpunkt aktualisieren

​Testzustellung senden

​Einen Endpunkt löschen

​Verwandte Themen

Ereigniskatalog

Webhooks-Übersicht

Endpunkte

Endpunktobjekt

Gültige Ereignistypen

Endpunktstatus

Endpunkte auflisten

Endpunkt erstellen

Anfragefelder

Endpunkt aktualisieren

Testzustellung senden

Einen Endpunkt löschen

Verwandte Themen