> ## 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.
# Punkty końcowe webhooków
> Zarządzaj wieloma adresami URL webhooków z sekretami i filtrami zdarzeń dla poszczególnych punktów końcowych.
System webhooków oparty na punktach końcowych pozwala zarejestrować **wiele**
miejsc docelowych na organizację, z których każde ma własny sekret, własny
status i własną subskrypcję podzbioru typów zdarzeń. Jest to zalecany
model dla wszystkich nowych integracji.
Porównaj ze [starszym webhookiem z jednym adresem URL](/api-reference/organizations#legacy-single-url-webhook),
który jest zachowany dla zgodności wstecznej, ale obsługuje tylko jeden adres URL na
organizację.
## Punkty końcowe
| Metoda | Ścieżka | Wymagana rola | Opis |
| -------- | ---------------------------------------------------- | ------------- | ----------------------------------------------- |
| `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Wyświetl listę punktów końcowych |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Utwórz punkt końcowy |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Zaktualizuj etykietę / URL / zdarzenia / status |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Usuń punkt końcowy |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Wyślij podpisane dostarczenie testowe |
## Obiekt punktu końcowego
```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"
}
```
| Pole | Typ | Opis |
| -------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | UUID | Identyfikator punktu końcowego |
| `label` | string | Nazwa wyświetlana, 1–120 znaków |
| `url` | string | Adres URL HTTPS; `http://localhost` dozwolony w środowisku deweloperskim |
| `events` | array of string | Typy subskrybowanych zdarzeń (zobacz [prawidłowe wartości](#valid-event-types)). Pusta tablica subskrybuje wszystkie zdarzenia |
| `status` | string | `active`, `disabled` (wstrzymany ręcznie) lub `failing` (ustawiany automatycznie, gdy dostarczenie wyczerpie 24-godzinny harmonogram ponawiania bez ani jednej odpowiedzi 2xx) |
| `secret_hint` | string | Pierwsze 4 i ostatnie 4 znaki sekretu podpisywania z wielokropkiem (`a1b2…9f0e`) — wystarczające do porównania z sekretem zapisanym lokalnie bez ujawniania pełnej wartości |
| `created_at`, `updated_at` | timestamp | |
Pełny `secret` punktu końcowego jest zwracany **tylko raz** podczas tworzenia i
nigdy więcej. Przechowuj go bezpiecznie — jeśli go utracisz, usuń punkt końcowy
i utwórz go ponownie.
### Prawidłowe typy zdarzeń
`events` jest walidowane względem dokładnie tego zestawu — wartości spoza listy
zwracają `400`. Zobacz [Katalog zdarzeń](/pl/webhooks/events), aby poznać strukturę
ładunku każdego typu.
* `telephony.incoming`, `telephony.complete`, `telephony.tool`
* `web.incoming`, `web.complete`, `web.tool`
* `call.graded`
* `issue.reported`
* `test-call.completed`
* `alert.triggered`
### Statusy punktów końcowych
* `active` — dostarczenia przebiegają normalnie.
* `disabled` — ręcznie wstrzymany przez `PATCH`. Żadne żądania nie są wysyłane. Nigdy
nie zmieniamy statusu punktu końcowego `disabled`; decyzja o przełączeniu go z powrotem na
`active` zawsze należy do Ciebie.
* `failing` — ustawiany automatycznie, gdy dostarczenie do punktu końcowego wyczerpie
cały harmonogram ponawiania (8 prób w ciągu 24 godzin), ani razu nie otrzymując odpowiedzi 2xx.
Punkt końcowy w stanie awarii nie otrzymuje dalszego ruchu.
Po naprawieniu punktu końcowego ustaw jego status z powrotem na `active` za pomocą `PATCH`;
dostarczenia, których harmonogram ponawiania jeszcze się nie wyczerpał, zostaną wznowione od miejsca,
w którym się zatrzymały.
***
## Wyświetl listę punktów końcowych
```bash cURL theme={null}
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Zwraca tablicę [obiektów punktu końcowego](#endpoint-object).
***
## Utwórz punkt końcowy
```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"]
```
### Pola żądania
| Pole | Typ | Wymagane | Opis |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label` | string | tak | 1–120 znaków |
| `url` | string | tak | Adres URL HTTPS (`http` dozwolony tylko dla `localhost` / `127.0.0.1`) |
| `events` | array | nie | Pusta lub pominięta wartość subskrybuje wszystkie zdarzenia. Należy użyć wartości wymienionych w sekcji [Prawidłowe typy zdarzeń](#valid-event-types); duplikaty są usuwane |
Zwraca `201 Created` z [obiektem punktu końcowego](#endpoint-object) oraz dodatkowym
polem najwyższego poziomu `secret`, zawierającym nieprzetworzony klucz podpisywania —
48-znakowy ciąg szesnastkowy:
```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` jest zwracany **wyłącznie podczas tworzenia**. Kolejne odpowiedzi `GET`
zawierają tylko `secret_hint`. Skopiuj pełną wartość do menedżera sekretów
przed odrzuceniem odpowiedzi.
***
## Zaktualizuj punkt końcowy
```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"]
}'
```
| Pole | Typ | Opis |
| -------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `label` | string | |
| `url` | string | |
| `events` | array | |
| `status` | string | `active` lub `disabled`. Ustaw `active`, aby ponownie włączyć punkt końcowy oznaczony przez serwer jako `failing` |
Zwraca `200 OK` ze zaktualizowanym [obiektem punktu końcowego](#endpoint-object).
***
## Wyślij dostarczenie testowe
Wyślij syntetyczne zdarzenie `webhook.test` do jednego punktu końcowego przy użyciu standardowego
potoku dostarczania, w tym kanonicznej serializacji JSON,
`X-ThunderPhone-Signature`, rejestrowania dostarczenia i obsługi ponowień.
Test jest kierowany do wybranego punktu końcowego niezależnie od jego filtra `events`.
```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"
```
Punkt końcowy otrzymuje kopertę podobną do tej:
```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"
}
```
API zwraca `200 OK` po pierwszej próbie, nawet jeśli miejsce docelowe
zwróci błąd. Sprawdź `success`, `status`, `response_code` i `error`,
aby poznać wynik dostarczenia:
```json theme={null}
{
"success": true,
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"event_type": "webhook.test",
"status": "delivered",
"response_code": 204,
"error": ""
}
```
`webhook.test` jest syntetyczne i nie można go dodać do subskrypcji `events`
punktu końcowego. Jeśli pierwsza próba się nie powiedzie, dostarczenie odbywa się według tego samego
harmonogramu ponowień co standardowe dostarczenia zdarzeń.
***
## Usuń endpoint
```bash cURL theme={null}
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Zwraca `204 No Content`. Dostarczanie do adresu URL zostaje natychmiast zatrzymane;
ponowne próby w toku są porzucane.
***
## Powiązane
Pełna lista wartości `events`, które możesz subskrybować.
Weryfikacja podpisu i semantyka dostarczania.