Tīmekļa aizķeru galapunkti

Pārvaldiet vairākus tīmekļa aizķeru URL ar katram galapunktam paredzētiem slepenajiem kodiem un notikumu filtriem.

Galapunktos balstītā tīmekļa aizķeru sistēma ļauj reģistrēt vairākus galamērķus katrai organizācijai, katru ar savu noslēpumu, savu statusu un savu abonementu noteiktai notikumu tipu apakškopai. Šis ir ieteicamais modelis visām jaunajām integrācijām.

Salīdziniet ar mantoto viena URL tīmekļa aizķeri, kas tiek uzturēta atpakaļsaderībai, bet atbalsta tikai vienu URL katrai organizācijai.

Galapunkti#

Galapunkta objekts#

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

Derīgie notikumu tipi#

events tiek validēts pret šo precīzo kopu — vērtības ārpus saraksta atgriež 400. Skatiet Notikumu katalogu, lai uzzinātu katra tipa slodzes struktūru.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (rezervēts; vēl netiek izsūtīts)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated nav balss aģenta konteksta, un tas tiek piegādāts tikai organizācijas mēroga galapunktiem.

voice.ready un voice.failed nevar atlasīt tieši. Lai tos saņemtu, izveidojiet organizācijas mēroga galapunktu ar events: []. Tukšs notikumu saraksts saņem visus atbalstītos notikumus, izņemot telephony.turn un web.turn, kuri jāatlasa tieši.

Galapunktu statusi#

• active — piegādes notiek normāli.
• disabled — manuāli apturēts, izmantojot PATCH. Pieprasījumi netiek sūtīti. Mēs nekad nemainām disabled galapunkta statusu; tā pārslēgšana atpakaļ uz active vienmēr ir jūsu ziņā.
• failing — tiek iestatīts automātiski, ja piegāde uz galapunktu izmanto visu atkārtojumu grafiku (8 mēģinājumi 24 stundu laikā), tā arī nesaņemot 2xx atbildi. Neveiksmīgs galapunkts vairs nesaņem datplūsmu. Kad tas notiek, mēs nosūtām e-pastu jūsu organizācijas īpašniekiem un administratoriem, un informācijas panelī tiek rādīts apturētais galapunkts ar pogu Atkārtoti aktivizēt. Kad galapunkts ir novērsts, ar PATCH mainiet tā statusu atpakaļ uz active; piegādes, kuru atkārtojumu grafiks vēl nav beidzies, turpinās no vietas, kur tās tika apturētas.

Galapunktu saraksts#

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Atgriež galapunktu objektu masīvu. Pievienojiet ?agent_id=42, lai atgrieztu tikai šim balss aģentam piesaistītos galapunktus.

Balss aģentam piesaistītie galapunkti#

Organizācijas mēroga galapunkti saņem katru atbilstošo notikumu. Galapunkts ar agent_id saņem tikai atbilstošos notikumus zvaniem, ko apkalpo šis balss aģents; notikumi bez balss aģenta konteksta, piemēram, alert.triggered, to nekad nesasniedz. Šos galapunktus varat arī izveidot un pārvaldīt balss aģenta veidotāja sadaļā Tīmekļa aizķeres.

Izveidojiet galapunktu#

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

Pieprasījuma lauki#

Atgriež 201 Created ar atjaunināto galapunkta objektu un papildu augstākā līmeņa lauku secret, kurā ir neapstrādāta parakstīšanas atslēga — 48 rakstzīmju heksadecimāla virkne:

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

Atjauniniet galapunktu#

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

Atgriež 200 OK ar atjaunināto galapunkta objektu.

Mainīt parakstīšanas noslēpumu#

Aizstājiet galapunkta parakstīšanas noslēpumu, piemēram, ja tas ir pazaudēts vai varētu būt noplūdis. Balss aģentam piesaistītam galapunktam varat izmantot arī vadības paneli: atveriet balss aģenta sadaļu Tīmekļa aizķeres un galapunktā atlasiet Ģenerēt noslēpumu no jauna. Organizācijas mēroga galapunktu noslēpumi tiek mainīti, izmantojot API.

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 '{}'

Atgriež 200 OK:

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

Nosūtīt testa piegādi#

Nosūtiet sintētisku webhook.test notikumu uz vienu galapunktu, izmantojot parasto piegādes konveijeru, tostarp kanonisko JSON serializāciju, abas paraksta galvenes, piegādes reģistrēšanu un atkārtotu mēģinājumu uzskaiti. Tests ir vērsts uz atlasīto galapunktu neatkarīgi no tā events filtra.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Galapunkts saņem šādu aploksni:

{
  "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 atgriež 200 OK pēc pirmā mēģinājuma, pat ja mērķis atgriež kļūdu. Pārbaudiet success, status, response_code un error, lai noteiktu piegādes rezultātu:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test ir sintētisks, un to nevar pievienot galapunkta events abonementam. Ja pirmais mēģinājums neizdodas, ThunderPhone to atkārto vienu reizi aptuveni pēc vienas minūtes un pēc tam apstājas; piegādei sadaļā Piegāžu atkļūdošana tiek rādīts status: "failed". Testa piegāde nekad neatzīmē galapunktu kā failing.

Lai konfigurētu trigeri reāla notikuma struktūrai, nododiet izvēles parametru event_type. Piegāde joprojām ir sintētiska un satur "sample": true; ar zvaniem saistītajos paraugos tiek izmantoti call_id: 0 un agent_id: 0.

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 pieņem jebkuru vērtību no Derīgie notikumu veidi. Ja to neiekļaujat, tiek saglabāta vispārējā webhook.test darbība.

Dzēst galapunktu#

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Atgriež 204 No Content. Piegāde uz URL tiek nekavējoties pārtraukta; notiekošie atkārtotie mēģinājumi tiek atcelti.

Piegāžu atkļūdošana#

Pirms secināt, ka webhook netika nosūtīts, pārbaudiet GET /v1/developer/webhook-deliveries. Tas parāda nesenos mēģinājumus no abām webhook sistēmām, tostarp zvana ID, URL izcelsmi, HTTP statusu, mēģinājumu skaitu, atļauto kļūdu kategoriju un nākamā atkārtotā mēģinājuma laiku. Tas nekad neatgriež notikuma slodzi, transkripciju, saglabāto kļūdas tekstu, atbildes pamattekstu vai URL ceļu.

To pašu neseno vēsturi varat skatīt arī sadaļā Aģenti → atlasiet aģentu → Webhooks → Nesenās piegādes. Rindās tiek rādīta galapunkta etiķete un URL izcelsme, ko izmantoja pēdējais mēģinājums. Tas ir darbības stāvoklis, nevis nemaināms audita žurnāls: galapunkta dzēšana dzēš arī tā piegāžu rindas.

Ja n8n atgriež 404, vispirms pārliecinieties, ka darbplūsma ir aktīva, pieņem POST un izmanto ražošanas webhook URL, nevis testa URL. 401 vai 403 norāda uz autentifikācijas vai paraksta validācijas problēmu; taimauti norāda uz mērķa aizkavi vai pieejamību; TLS kļūdas norāda uz sertifikātu ķēdi, resursdatora nosaukumu vai derīguma termiņu.

Saistīts#