> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook-Endpunkte
> Verwalten Sie mehrere Webhook-URLs mit endpunktspezifischen 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 [veralteten Single-URL-Webhook](/api-reference/organizations#legacy-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
```json theme={null}
{
"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](#valid-event-types)). 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](/de/webhooks/events) 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
```bash cURL theme={null}
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Gibt ein Array von [Endpunktobjekten](#endpoint-object) zurück.
***
## Endpunkt erstellen
```bash cURL theme={null}
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"]
}'
```
```python Python theme={null}
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](#valid-event-types) aufgeführten Werte verwendet werden; Duplikate werden entfernt |
Gibt `201 Created` mit dem [Endpunktobjekt](#endpoint-object) sowie
einem zusätzlichen `secret`-Feld der obersten Ebene zurück, das den rohen Signaturschlüssel enthält — eine
48 Zeichen lange Hexadezimalzeichenfolge:
```json theme={null}
{
"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
```bash cURL theme={null}
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](#endpoint-object) 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.
```bash cURL theme={null}
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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
```bash cURL theme={null}
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 Themen
Die vollständige Liste der `events`-Werte, die Sie abonnieren können.
Signaturprüfung und Zustellungssemantik.