Webhooks

Webhook Uç Noktaları

Uç nokta başına gizli anahtarlar ve olay filtreleriyle birden fazla webhook URL

Uç nokta tabanlı webhook sistemi, kuruluş başına her biri kendi gizli anahtarına, durumuna ve etkinlik türlerinin bir alt kümesine yönelik aboneliğine sahip birden fazla hedef kaydetmenizi sağlar. Bu, tüm yeni entegrasyonlar için önerilen modeldir.

Geriye dönük uyumluluk için korunan ancak kuruluş başına yalnızca bir URL'yi destekleyen eski tek URL webhook'u ile karşılaştırın.

Uç noktalar#

Uç nokta nesnesi#

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

Geçerli etkinlik türleri#

events, tam olarak bu kümeye göre doğrulanır — liste dışındaki değerler 400 döndürür. Her türün yük biçimi için Etkinlik kataloğuna bakın.

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

Uç nokta durumları#

• active — teslimatlar normal şekilde devam eder.
• disabled — PATCH aracılığıyla manuel olarak duraklatılır. Hiçbir istek gönderilmez. Bir disabled uç noktanın durumunu asla değiştirmeyiz; yeniden active durumuna getirip getirmemek her zaman sizin kararınızdır.
• failing — uç noktaya yapılan bir teslimat, hiç 2xx almadan tüm yeniden deneme planını (24 saat boyunca 8 deneme) tükettiğinde otomatik olarak ayarlanır. Başarısız bir uç noktaya daha fazla trafik gönderilmez. Uç nokta düzeltildiğinde, PATCH ile durumunu yeniden active yapın; yeniden deneme planı henüz sona ermemiş teslimatlar kaldıkları yerden devam eder.

Uç noktaları listele#

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

Bir Uç nokta nesneleri dizisi döndürür.

Uç nokta oluşturma#

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

İstek alanları#

Ek üst düzey secret alanıyla birlikte Uç nokta nesnesini içeren 201 Created döndürür. Bu alan, ham imzalama anahtarını içeren 48 karakterlik bir hex dizesidir:

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

Uç nokta güncelleme#

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

Güncellenmiş Uç nokta nesnesi ile 200 OK döndürür.

Test teslimatı gönderin#

Kanonik JSON serileştirmesi, X-ThunderPhone-Signature, teslimat kaydı ve yeniden deneme takibi dahil olmak üzere normal teslimat işlem hattını kullanarak bir uç noktaya sentetik bir webhook.test olayı gönderin. Test, events filtresinden bağımsız olarak seçilen uç noktayı hedefler.

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

Uç nokta aşağıdakine benzer bir zarf alır:

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

Hedef bir hata döndürse bile API, ilk denemeden sonra 200 OK döndürür. Teslimat sonucunu görmek için success, status, response_code ve error alanlarını inceleyin:

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

webhook.test sentetiktir ve bir uç noktanın events aboneliğine eklenemez. İlk deneme başarısız olursa teslimat, normal olay teslimatlarıyla aynı yeniden deneme planını izler.

Uç noktayı silin#

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

204 No Content döndürür. URL'ye teslimat hemen durur; devam eden yeniden denemeler iptal edilir.

İlgili kaynaklar#