Webhook Uç Noktaları

Uç nokta tabanlı webhook sistemi, kuruluş başına birden fazla hedef kaydetmenize olanak tanır; her birinin kendi gizli anahtarı, kendi durumu ve etkinlik türlerinin bir alt kümesine yönelik kendi aboneliği vardır. 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’li webhook ile karşılaştırın.

Uç noktalar

Yöntem	Yol	Gerekli rol	Açıklama
`GET`	`/v1/developer/webhook-endpoints`	`admin+`	Uç noktaları listele
`POST`	`/v1/developer/webhook-endpoints`	`admin+`	Uç nokta oluştur
`PATCH`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Etiketi / URL’yi / etkinlikleri / durumu güncelle
`DELETE`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Uç noktayı sil
`POST`	`/v1/developer/webhook-endpoints/{endpoint_id}/test`	`admin+`	İmzalı test teslimatı gönder

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

Alan	Tür	Açıklama
`id`	UUID	Uç nokta kimliği
`label`	string	Görünen ad, 1–120 karakter
`url`	string	HTTPS URL’si; geliştirme için `http://localhost` kullanılabilir
`events`	string dizisi	Abone olunan etkinlik türleri (geçerli değerlere bakın). Boş dizi tüm etkinliklere abone olur
`status`	string	`active`, `disabled` (manuel olarak duraklatıldı) veya `failing` (bir teslimat tek bir 2xx bile almadan 24 saatlik yeniden deneme planını tükettiğinde otomatik olarak ayarlanır)
`secret_hint`	string	Üç noktayla (`a1b2…9f0e`) birlikte imzalama gizli anahtarının ilk 4 ve son 4 karakteri — tam değeri göstermeden yerel olarak kaydettiğiniz gizli anahtarla çapraz doğrulama yapmanız için yeterlidir
`created_at`, `updated_at`	zaman damgası

Uç noktanın tam secret değeri oluşturma sırasında bir kez döndürülür ve bir daha asla döndürülmez. Güvenli bir şekilde saklayın — kaybederseniz uç noktayı silin ve yeniden oluşturun.

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 Etkinlikler kataloğuna bakın.

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

Uç nokta durumları

active — teslimatlar normal şekilde gerçekleşir.
disabled — PATCH ile manuel olarak duraklatılır. Hiçbir istek gönderilmez. disabled durumundaki bir uç noktanın durumunu asla değiştirmeyiz; tekrar active durumuna almak 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 içinde 8 deneme) tükettiğinde otomatik olarak ayarlanır. Başarısız durumdaki bir uç nokta başka trafik almaz. Uç nokta düzeltildiğinde, durumunu PATCH ile tekrar active olarak ayarlayın; yeniden deneme planı henüz tükenmemiş 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"

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ı

Alan	Tür	Zorunlu	Açıklama
`label`	dize	evet	1–120 karakter
`url`	dize	evet	HTTPS URL’si (`http` yalnızca `localhost` / `127.0.0.1` için izinlidir)
`events`	dizi	hayır	Boş bırakıldığında/atlanıldığında tüm etkinliklere abone olunur. Geçerli etkinlik türleri bölümünde listelenen değerler kullanılmalıdır; yinelenenler kaldırılır

Uç Nokta nesnesi ile birlikte ham imzalama anahtarını içeren ek bir üst düzey secret alanıyla 201 Created döner — 48 karakterlik bir hex dizesi:

{
  "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 yalnızca oluşturma sırasında döner. Sonraki GET yanıtları yalnızca secret_hint içerir. Yanıtı kapatmadan önce tam değeri gizli anahtar yöneticinize kopyalayın.

Uç noktayı 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"]
  }'

Alan	Tür	Açıklama
`label`	dize
`url`	dize
`events`	dizi
`status`	dize	`active` veya `disabled`. Sunucunun `failing` olarak işaretlediği bir uç noktayı yeniden etkinleştirmek için `active` olarak ayarlayın

Güncellenmiş Uç Nokta nesnesi ile 200 OK döner.

Test teslimatı gönderme

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 etkinliği gönderin. Test, events filtresinden bağımsız olarak seçili 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öner. 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 etkinlik teslimatlarıyla aynı yeniden deneme zamanlaması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

Olay kataloğu

Abone olabileceğiniz events değerlerinin tam listesi.

Webhook'lara genel bakış

İmza doğrulama ve teslimat semantiği.

Webhooks

Function Tools

Uç noktalar

Uç nokta nesnesi

Geçerli etkinlik türleri

Uç nokta durumları

Uç noktaları listele

Uç nokta oluşturma

İstek alanları

Uç noktayı güncelleme

Test teslimatı gönderme

Uç noktayı silin

İlgili

Olay kataloğu

Webhook'lara genel bakış

​Uç noktalar

​Uç nokta nesnesi

​Geçerli etkinlik türleri

​Uç nokta durumları

​Uç noktaları listele

​Uç nokta oluşturma

​İstek alanları

​Uç noktayı güncelleme

​Test teslimatı gönderme

​Uç noktayı silin

​İlgili

Olay kataloğu

Webhook'lara genel bakış

Uç noktalar

Uç nokta nesnesi

Geçerli etkinlik türleri

Uç nokta durumları

Uç noktaları listele

Uç nokta oluşturma

İstek alanları

Uç noktayı güncelleme

Test teslimatı gönderme

Uç noktayı silin

İlgili