> ## 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.
# Endpointuri webhook
> Gestionați mai multe URL-uri webhook cu secrete pentru fiecare endpoint și filtre de evenimente.
Sistemul de webhookuri bazat pe endpointuri vă permite să înregistrați **mai multe**
destinații pentru fiecare organizație, fiecare cu propriul secret, propriul
status și propriul abonament la un subset de tipuri de evenimente. Acesta este
modelul recomandat pentru toate integrările noi.
Comparați cu [webhookul cu un singur URL moștenit](/api-reference/organizations#legacy-single-url-webhook),
care este păstrat pentru compatibilitate retroactivă, dar acceptă un singur URL
per organizație.
## Endpointuri
| Metodă | Cale | Rol necesar | Descriere |
| -------- | ---------------------------------------------------- | ----------- | ------------------------------------------------------- |
| `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Listați endpointurile |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Creați un endpoint |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Actualizați eticheta / URL-ul / evenimentele / statusul |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Ștergeți un endpoint |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Trimiteți o livrare de test semnată |
## Obiect endpoint
```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"
}
```
| Câmp | Tip | Descriere |
| -------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | UUID | ID-ul endpointului |
| `label` | string | Nume afișat, 1–120 de caractere |
| `url` | string | URL HTTPS; `http://localhost` este permis pentru dezvoltare |
| `events` | array of string | Tipuri de evenimente abonate (consultați [valorile valide](#valid-event-types)). Un array gol se abonează la toate evenimentele |
| `status` | string | `active`, `disabled` (pus manual pe pauză) sau `failing` (setat automat când o livrare își epuizează programul de reîncercări de 24 h fără niciun 2xx) |
| `secret_hint` | string | Primele 4 și ultimele 4 caractere ale secretului de semnare, cu puncte de suspensie (`a1b2…9f0e`) — suficiente pentru a verifica secretul salvat local fără a expune valoarea completă |
| `created_at`, `updated_at` | timestamp | |
`secret`-ul complet al endpointului este returnat **o singură dată** la creare
și niciodată după aceea. Stocați-l în siguranță — dacă îl pierdeți, ștergeți endpointul
și creați-l din nou.
### Tipuri de evenimente valide
`events` este validat în raport cu acest set exact — valorile din afara listei
returnează `400`. Consultați [Catalogul de evenimente](/ro/webhooks/events) pentru structura
payloadului fiecărui tip.
* `telephony.incoming`, `telephony.complete`, `telephony.tool`
* `web.incoming`, `web.complete`, `web.tool`
* `call.graded`
* `issue.reported`
* `test-call.completed`
* `alert.triggered`
### Statusuri ale endpointurilor
* `active` — livrările circulă normal.
* `disabled` — pus manual pe pauză prin `PATCH`. Nu sunt trimise cereri. Nu
schimbăm niciodată statusul unui endpoint `disabled`; revenirea la
`active` depinde întotdeauna de dumneavoastră.
* `failing` — setat automat atunci când o livrare către endpoint își parcurge
întregul program de reîncercări (8 încercări în 24 de ore) fără să primească
vreodată un 2xx. Un endpoint în stare de eșec nu mai primește trafic.
După ce remediați endpointul, actualizați-i statusul înapoi la `active` prin `PATCH`;
livrările al căror program de reîncercări nu s-a încheiat încă reiau de unde
au rămas.
***
## Listați endpointurile
```bash cURL theme={null}
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Returnează un array de [obiecte endpoint](#endpoint-object).
***
## Creați un endpoint
```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"]
```
### Câmpuri de solicitare
| Câmp | Tip | Obligatoriu | Descriere |
| -------- | ------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label` | șir | da | 1–120 de caractere |
| `url` | șir | da | URL HTTPS (`http` permis numai pentru `localhost` / `127.0.0.1`) |
| `events` | matrice | nu | Gol/omis se abonează la toate evenimentele. Trebuie să utilizați valorile enumerate în [Tipuri de evenimente valide](#valid-event-types); duplicatele sunt eliminate |
Returnează `201 Created` cu [obiectul endpoint](#endpoint-object), plus
un câmp suplimentar `secret` la nivelul superior, care conține cheia brută de semnare — un
șir hexazecimal de 48 de caractere:
```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` este returnat **numai la creare**. Răspunsurile `GET` ulterioare
includ numai `secret_hint`. Copiați valoarea completă în managerul dumneavoastră
de secrete înainte de a închide răspunsul.
***
## Actualizați un endpoint
```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"]
}'
```
| Câmp | Tip | Descriere |
| -------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `label` | șir | |
| `url` | șir | |
| `events` | matrice | |
| `status` | șir | `active` sau `disabled`. Setați `active` pentru a reactiva un endpoint pe care serverul l-a marcat ca `failing` |
Returnează `200 OK` cu [obiectul endpoint](#endpoint-object) actualizat.
***
## Trimiteți o livrare de test
Trimiteți un eveniment sintetic `webhook.test` către un endpoint utilizând fluxul normal
de livrare, inclusiv serializarea JSON canonică,
`X-ThunderPhone-Signature`, înregistrarea livrării și gestionarea reîncercărilor.
Testul vizează endpointul selectat, indiferent de filtrul său `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"
```
Endpointul primește un plic precum:
```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-ul returnează `200 OK` după prima încercare, chiar dacă destinația
returnează o eroare. Verificați `success`, `status`, `response_code` și `error`
pentru rezultatul livrării:
```json theme={null}
{
"success": true,
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"event_type": "webhook.test",
"status": "delivered",
"response_code": 204,
"error": ""
}
```
`webhook.test` este sintetic și nu poate fi adăugat la abonamentul `events`
al unui endpoint. Dacă prima încercare eșuează, livrarea urmează același
program de reîncercări ca livrările de evenimente normale.
***
## Ștergeți un 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"
```
Returnează `204 No Content`. Livrarea către URL se oprește imediat;
reîncercările în curs sunt abandonate.
***
## Resurse conexe
Lista completă a valorilor `events` la care vă puteți abona.
Verificarea semnăturii și semantica livrării.