---
title: "Endpointuri webhook"
description: "Gestionați mai multe URL-uri webhook cu secrete și filtre de evenimente pentru fiecare endpoint."
---

Sistemul de webhook-uri bazat pe endpointuri vă permite să înregistrați **mai multe**
destinații per organizație, fiecare cu propriul secret, propriul
status și propria abonare la un subset de tipuri de evenimente. Acesta este
modelul recomandat pentru toate integrările noi.

Comparați cu [webhook-ul vechi cu un singur URL](/api-reference/organizations#legacy-single-url-webhook),
care este păstrat pentru compatibilitate inversă, dar acceptă un singur URL per
organizație.

## Endpointuri

| Metodă | Cale | Rol necesar | Descriere |
|--------|------|---------------|-------------|
| `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Listează endpointurile |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Creează un endpoint |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Actualizează eticheta / URL-ul / evenimentele / starea |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Șterge un endpoint |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret` | `admin+` | Înlocuiește secretul de semnare |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Trimite o livrare de test semnată |
| `GET` | `/v1/developer/webhook-deliveries` | `admin+` | Inspectează rezultatele recente ale livrărilor endpointurilor și ale livrărilor moștenite |

## Obiect endpoint

```json
{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "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 | Numele afișat, 1–120 de caractere |
| `url` | string | URL HTTPS; `http://localhost` este permis pentru dezvoltare |
| `events` | array de string | Tipurile de evenimente la care sunteți abonat(ă) (consultați [valorile valide](#valid-event-types)). O matrice goală vă abonează la toate evenimentele, cu excepția evenimentelor pe tură disponibile doar prin abonare explicită (`telephony.turn` / `web.turn`) |
| `status` | string | `active`, `disabled` (pus pe pauză manual) sau `failing` (setat automat când o livrare își epuizează programul de reîncercări de 24 h fără niciun răspuns 2xx) |
| `agent_id` | integer \| null | Agentul căruia îi este asociat acest endpoint; `null` înseamnă la nivelul întregii organizații |
| `agent_name` | string \| null | Numele agentului asociat sau `null` pentru un endpoint la nivelul întregii organizații |
| `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ă |
| `paused_at` | timestamp \| null | Momentul în care ThunderPhone a setat endpointul la `failing`. `null` cât timp acesta este `active` sau `disabled` |
| `pause_last_error` | string | Ultima eroare de livrare când endpointul a fost pus pe pauză, de exemplu `HTTP 503: Service Unavailable`. Gol, cu excepția cazului `failing` |
| `pause_undelivered_count` | integer \| null | Evenimente nelivrate de la ultima livrare reușită a endpointului, numărate când acesta a fost pus pe pauză |
| `created_at`, `updated_at` | timestamp | |

<Note>
  Valoarea completă a `secret`-ului endpointului este returnată **o singură dată** la creare și
  niciodată ulterior. Stocați-o în siguranță — dacă o pierdeți,
  [rotiți-l](#rotate-the-signing-secret) pentru a obține unul nou.
</Note>

### 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`, `telephony.turn`
- `web.incoming`, `web.complete`, `web.tool`, `web.turn`
- `sms.sent`, `sms.failed`
- `sms.received` (rezervat; nu este emis încă)
- `call.graded`, `call.data_extracted`, `call.transfer_completed`
- `campaign.completed`
- `issue.reported`, `issue.escalated`
- `test-call.completed`
- `alert.triggered`

`issue.escalated` nu are context de agent și este livrat numai endpointurilor
la nivelul întregii organizații.

`voice.ready` și `voice.failed` nu pot fi selectate explicit. Pentru a le primi,
creați un endpoint la nivelul întregii organizații cu `events: []`. O listă goală de evenimente
primește toate evenimentele acceptate, cu excepția `telephony.turn` și `web.turn`,
care trebuie selectate explicit.

### Stări ale endpointului

- `active` — livrările se desfășoară normal.
- `disabled` — pus manual pe pauză prin `PATCH`. Nu sunt trimise solicitări. Nu modificăm niciodată starea unui endpoint `disabled`; revenirea la `active` depinde întotdeauna de dumneavoastră.
- `failing` — setat automat atunci când o livrare către endpoint își epuizează întregul program de reîncercări (8 încercări în 24 de ore) fără să primească vreodată un răspuns 2xx. Un endpoint în stare de eșec nu mai primește trafic. Trimitem un e-mail proprietarilor și administratorilor organizației dumneavoastră când se întâmplă acest lucru, iar tabloul de bord afișează endpointul pus pe pauză cu un buton Reactivare. După remedierea endpointului, aplicați `PATCH` pentru a-i schimba starea înapoi la `active`; livrările al căror program de reîncercări nu s-a epuizat încă reiau de unde au rămas.

---

## Lista endpointurilor

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returnează o matrice de [obiecte endpoint](#endpoint-object).
Transmiteți `?agent_id=42` pentru a returna numai endpointurile limitate la acel agent.

### Endpointuri limitate la agent

Endpointurile la nivelul întregii organizații primesc fiecare eveniment corespunzător. Un endpoint cu
`agent_id` primește numai evenimentele corespunzătoare pentru apelurile gestionate de acel agent;
evenimentele fără context de agent, precum `alert.triggered`, nu ajung niciodată la acesta. De asemenea,
puteți crea și gestiona aceste endpointuri din secțiunea
**Webhookuri** a constructorului de agenți.

## Creați un endpoint

<CodeGroup>
```bash cURL
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
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"]
```
</CodeGroup>

### Câmpuri de solicitare

| Câmp | Tip | Obligatoriu | Descriere |
|-------|------|----------|-------------|
| `label` | șir | da | 1–120 de caractere |
| `url` | șir | da | URL HTTPS (`http` este permis numai pentru `localhost` / `127.0.0.1`) |
| `events` | matrice | nu | Gol/omis se abonează la toate evenimentele, cu excepția `telephony.turn` / `web.turn`, care necesită un abonament explicit. Trebuie să utilizați valorile listate în [Tipuri de evenimente valide](#valid-event-types); duplicatele sunt eliminate |
| `agent_id` | întreg \| nul | nu | Limitați livrarea la un agent din această organizație; omiteți sau utilizați `null` pentru un endpoint la nivelul întregii organizații |

Returnează `201 Created` cu [obiectul Endpoint](#endpoint-object), plus
un câmp suplimentar `secret` de nivel superior care conține cheia brută de semnare — un
șir hexazecimal de 48 de caractere:

```json
{
  "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"
}
```

<Warning>
  `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.
</Warning>

---

## Actualizați un endpoint

<CodeGroup>
```bash cURL
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"]
  }'
```
</CodeGroup>

| 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` |
| `agent_id` | întreg \| nul | Setați un ID de agent pentru a limita endpointul sau `null` pentru a-l face disponibil la nivelul întregii organizații |

Returnează `200 OK` cu [obiectul Endpoint](#endpoint-object) actualizat.

---

## Rotiți secretul de semnare

Înlocuiți secretul de semnare al unui endpoint, de exemplu dacă a fost pierdut sau
este posibil să fi fost divulgat. Pentru un endpoint asociat unui agent, puteți utiliza și
tabloul de bord: deschideți secțiunea **Webhook-uri** a agentului și selectați
**Regenerați secretul** pentru endpoint. Endpointurile la nivel de organizație sunt
rotite prin API.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```
</CodeGroup>

| Câmp | Tip | Obligatoriu | Descriere |
|-------|------|----------|-------------|
| `include_copies` | boolean | nu | Valoarea implicită este `true`. Oferă, de asemenea, noul secret celorlalte endpointuri ale organizației dumneavoastră care au același URL și același secret curent, cum ar fi copii ale acestui endpoint pentru alți agenți, astfel încât un singur receptor să continue verificarea cu un singur secret |

Returnează `200 OK`:

```json
{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}
```

| Câmp | Tip | Descriere |
|-------|------|-------------|
| `endpoint` | obiect | [Obiectul Endpoint](#endpoint-object) cu noul său `secret_hint` |
| `secret` | șir | Noul secret de semnare. Este returnat numai în acest răspuns |
| `rotated_endpoint_ids` | matrice de UUID-uri | Fiecare endpoint care utilizează acum noul secret |

<Warning>
  Vechiul secret încetează să fie utilizat imediat: următoarea livrare,
  inclusiv reîncercările, este semnată cu cel nou. Până când receptorul dumneavoastră are
  noul secret, livrările nu trec verificarea semnăturii; dacă răspunde
  la acestea cu un status non-2xx, ele sunt reîncercate conform programului obișnuit de 24 h,
  așa că actualizați receptorul cât mai curând. Dacă receptorul dumneavoastră este implementat
  în etape, configurați-l să accepte ambele secrete în timpul implementării — funcțiile ajutătoare
  de verificare din SDK acceptă o listă de secrete (consultați
  [Verificați semnăturile webhook](/ro/guides/verify-webhook-signatures)).
</Warning>

---

## Trimiteți o livrare de test

Trimiteți un eveniment sintetic `webhook.test` către un endpoint folosind fluxul normal de
livrare, inclusiv serializarea JSON canonică, ambele antete de
semnătură, înregistrarea livrării și evidența reîncercărilor.
Testul vizează endpointul selectat indiferent de filtrul său `events`.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Endpointul primește un plic precum:

```json
{
  "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
{
  "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ă, ThunderPhone o reîncearcă o dată,
aproximativ un minut mai târziu, apoi se oprește; livrarea afișează atunci `status: "failed"`
în [Depanarea livrărilor](#debug-deliveries). O livrare de test nu marchează niciodată
endpointul ca `failing`.

Pentru a configura un declanșator bazat pe structura unui eveniment real, transmiteți un
`event_type` opțional. Livrarea rămâne sintetică și conține `"sample": true`;
mostrele asociate apelurilor folosesc `call_id: 0` și `agent_id: 0`.

```bash
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'
```

`event_type` acceptă orice valoare din [Tipuri de evenimente valide](#valid-event-types).
Omiterea acestuia păstrează comportamentul generic `webhook.test`.

---

## Ștergeți un endpoint

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returnează `204 No Content`. Livrarea către URL se oprește imediat;
reîncercările aflate în curs sunt abandonate.

---

## Depanarea livrărilor

Înainte de a concluziona că un webhook nu a fost trimis, verificați
[`GET /v1/developer/webhook-deliveries`](/api-reference/webhook-deliveries).
Aceasta afișează încercările recente din ambele sisteme de webhook, inclusiv ID-ul apelului,
originea URL-ului, starea HTTP, numărul de încercări, categoria de eșec permisă și următoarea
oră de reîncercare. Nu returnează niciodată sarcina utilă a evenimentului, transcrierea, textul erorii stocate,
corpul răspunsului sau calea URL-ului.

Puteți vedea același istoric recent și în **Agenți → selectați un agent → Webhook-uri →
Livrări recente**. Rândurile afișează eticheta endpointului și originea URL-ului utilizată de cea mai recentă
încercare. Aceasta este o stare operațională, nu un jurnal de audit imuabil: ștergerea unui endpoint
șterge și rândurile sale de livrare.

Pentru un `404` n8n, confirmați mai întâi că fluxul de lucru este activ, acceptă `POST` și utilizează
URL-ul webhook de producție, nu URL-ul de test. Un `401` sau `403` indică
autentificarea sau validarea semnăturii; expirările de timp indică latența
sau disponibilitatea destinației; erorile TLS indică lanțul de certificate, numele gazdei sau expirarea.

---

## Asociate

<CardGroup cols={2}>
  <Card title="Catalog de evenimente" icon="list" href="/ro/webhooks/events">
    Lista completă a valorilor `events` la care vă puteți abona.
  </Card>
  <Card title="Prezentare generală a webhook-urilor" icon="bolt" href="/ro/webhooks/overview">
    Verificarea semnăturii și semantica livrării.
  </Card>
</CardGroup>