Webhook крайни точки

Системата за уебкуки, базирана на крайни точки, Ви позволява да регистрирате множество дестинации за организация, всяка със собствена тайна, собствен статус и собствен абонамент за подмножество от типове събития. Това е препоръчителният модел за всички нови интеграции.

Сравнете с остарелия уебкук с един URL, който се запазва за обратна съвместимост, но поддържа само един URL за организация.

Крайни точки

Обект на крайна точка

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

Валидни типове събития

events се валидира спрямо този точен набор — стойности извън списъка връщат 400. Вижте Каталога на събитията за формата на payload за всеки тип.

• telephony.incoming, telephony.complete, telephony.tool
• web.incoming, web.complete, web.tool
• call.graded
• issue.reported
• test-call.completed
• alert.triggered

Статуси на крайните точки

• active — доставките протичат нормално.
• disabled — ръчно спрян чрез PATCH. Не се изпращат заявки. Ние никога не променяме статуса на крайна точка с disabled; връщането му на active винаги е Ваше решение.
• failing — задава се автоматично, когато доставка до крайната точка изчерпи целия си график за повторни опити (8 опита за 24 часа), без никога да получи 2xx. Крайна точка с неуспешен статус не получава допълнителен трафик. След като крайната точка бъде поправена, задайте чрез PATCH статуса ѝ обратно на active; доставките, чийто график за повторни опити все още не е изчерпан, продължават оттам, докъдето са стигнали.

Извеждане на списък с крайни точки

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

Връща масив от обекти на крайни точки.

Създаване на крайна точка

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

Полета на заявката

Връща 201 Created с обекта на крайната точка и допълнително поле secret от най-горно ниво, съдържащо необработения ключ за подписване — 48-символен шестнадесетичен низ:

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

Актуализиране на крайна точка

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

Връща 200 OK с актуализирания обект на крайната точка.

Изпращане на тестова доставка

Изпратете синтетично събитие webhook.test до една крайна точка чрез стандартния конвейер за доставка, включително канонична JSON сериализация, X-ThunderPhone-Signature, записване на доставката и отчитане на повторните опити. Тестът е насочен към избраната крайна точка независимо от нейния филтър events.

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

Крайната точка получава обвивка от вида:

{
  "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 връща 200 OK след първия опит, дори ако местоназначението върне грешка. Проверете success, status, response_code и error за резултата от доставката:

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

webhook.test е синтетично и не може да бъде добавено към абонамента events на крайна точка. Ако първият опит е неуспешен, доставката следва същия график за повторни опити като обикновените доставки на събития.

Изтриване на крайна точка

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

Връща 204 No Content. Доставката до URL адреса спира незабавно; повторните опити в ход се прекратяват.

Свързано