Webhooks

Webhook-Endpunkte

Verwalten Sie mehrere Webhook-URLs mit Endpunkt-spezifischen Secrets und Ereignisfiltern.

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 Legacy-Single-URL-Webhook, der aus Gründen der Abwärtskompatibilität beibehalten wird, aber nur eine URL pro Organisation unterstützt.

Endpunkte#

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"
}

Gültige Ereignistypen#

events wird anhand dieser exakten Menge validiert — Werte außerhalb der Liste geben 400 zurück. Informationen zur Nutzlaststruktur der einzelnen Typen finden Sie im Ereigniskatalog.

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

Endpunktstatus#

• active — Zustellungen werden normal durchgeführt.
• disabled — manuell über PATCH pausiert. Es werden keine Anfragen gesendet. Wir ändern den Status eines disabled-Endpunkts nie; die Rücksetzung auf active liegt immer bei Ihnen.
• failing — wird automatisch gesetzt, wenn eine Zustellung an den Endpunkt ihren gesamten Wiederholungsplan (8 Versuche innerhalb von 24 Stunden) ausschöpft, ohne jemals ein 2xx zu erhalten. Ein fehlerhafter Endpunkt erhält keinen weiteren Datenverkehr. Sobald der Endpunkt behoben ist, setzen Sie seinen Status per PATCH wieder auf active; Zustellungen, deren Wiederholungsplan noch nicht abgelaufen ist, werden dort fortgesetzt, wo 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#

Gibt 201 Created mit dem Endpunktobjekt sowie einem zusätzlichen secret-Feld auf oberster Ebene zurück, das den rohen Signaturschlüssel enthält — eine 48-stellige 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"
}

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"]
  }'

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 zielt unabhängig von seinem events-Filter auf 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 eine Umhüllung wie diese:

{
  "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 Zustellungsergebnis:

{
  "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. Falls der erste Versuch fehlschlägt, folgt die Zustellung demselben Wiederholungszeitplan wie normale Ereigniszustellungen.

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.

Verwandte Inhalte#