Webhook Uç Noktaları

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

Uç nokta tabanlı webhook sistemi, kuruluş başına birden fazla hedef kaydetmenizi sağlar. Her hedefin kendi gizli anahtarı, kendi durumu ve olay 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#

Uç nokta nesnesi#

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

Geçerli etkinlik türleri#

events, tam olarak bu kümeye göre doğrulanır — listedeki değerlerin dışındaki değerler 400 döndürür. Her türün yük yapısı için Etkinlikler kataloğu sayfasına bakın.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (ayrılmıştır; henüz gönderilmemektedir)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated için ajan bağlamı yoktur ve yalnızca kuruluş genelindeki uç noktalara teslim edilir.

voice.ready ve voice.failed açıkça seçilemez. Bunları almak için events: [] ile kuruluş genelinde bir uç nokta oluşturun. Boş bir etkinlik listesi, açıkça seçilmesi gereken telephony.turn ve web.turn dışındaki desteklenen tüm etkinlikleri alır.

Uç nokta durumları#

• active — teslimatlar normal şekilde gerçekleşir.
• disabled — PATCH aracılığıyla manuel olarak duraklatılır. Hiçbir istek gönderilmez. disabled bir uç noktanın durumunu asla değiştirmeyiz; onu yeniden active durumuna getirmek 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 bir uç nokta daha fazla trafik almaz. Bu gerçekleştiğinde kuruluşunuzun sahiplerine ve yöneticilerine e-posta göndeririz; pano, duraklatılmış uç noktayı Yeniden etkinleştir düğmesiyle gösterir. Uç nokta düzeltildiğinde, durumunu PATCH ile yeniden active olarak ayarlayın; yeniden deneme planı henüz tükenmemiş teslimatlar kaldıkları yerden devam eder.

Uç noktaları listeleme#

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. Yalnızca o ajanın kapsamındaki uç noktaları döndürmek için ?agent_id=42 parametresini iletin.

Ajan kapsamındaki uç noktalar#

Kuruluş genelindeki uç noktalar, eşleşen tüm etkinlikleri alır. agent_id değerine sahip bir uç nokta yalnızca o ajanın işlediği aramalarla eşleşen etkinlikleri alır; alert.triggered gibi ajan bağlamı olmayan etkinlikler ona asla ulaşmaz. Bu uç noktaları ayrıca ajan oluşturucunun Webhook'lar bölümünden oluşturabilir ve yönetebilirsiniz.

Bir uç nokta oluşturun#

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ı#

Uç nokta nesnesi ile birlikte ham imzalama anahtarını içeren ek bir üst düzey secret alanıyla 201 Created döndürür — 48 karakterlik onaltılık bir dize:

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

Bir uç noktayı güncelleyin#

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.

İmzalama gizli anahtarını döndürün#

Bir uç noktanın imzalama gizli anahtarını, örneğin kaybolduğunda veya sızdırılmış olabileceğinde değiştirin. Ajan kapsamındaki bir uç nokta için panoyu da kullanabilirsiniz: ajanın Webhooks bölümünü açın ve uç noktada Gizli anahtarı yeniden oluştur seçeneğini belirleyin. Kuruluş genelindeki uç noktalar API üzerinden döndürülür.

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

200 OK döndürür:

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

Test teslimatı gönderin#

Normal teslimat işlem hattını kullanarak tek bir uç noktaya sentetik bir webhook.test olayı gönderin. Buna kanonik JSON serileştirmesi, her iki imza başlığı, teslimat kaydı ve yeniden deneme takibi dahildir.
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ğıdaki gibi 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 ThunderPhone yaklaşık bir dakika sonra bir kez yeniden dener ve ardından durur; teslimat daha sonra Hata ayıklama teslimatları altında status: "failed" olarak görünür. Test teslimatı hiçbir zaman uç noktayı failing olarak işaretlemez.

Gerçek bir olay biçimine göre tetikleyici yapılandırmak için isteğe bağlı bir event_type iletin. Teslimat yine sentetiktir ve "sample": true içerir; arama ile ilgili örneklerde call_id: 0 ve agent_id: 0 kullanılır.

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, Geçerli olay türleri içindeki herhangi bir değeri kabul eder. Bu alanı atlamak, genel webhook.test davranışını korur.

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 bırakılır.

Teslimatlarda hata ayıklayın#

Bir webhook'un gönderilmediği sonucuna varmadan önce GET /v1/developer/webhook-deliveries uç noktasını inceleyin. Bu uç nokta, arama kimliği, URL kaynağı, HTTP durumu, deneme sayısı, izin listesindeki hata kategorisi ve sonraki yeniden deneme zamanı dahil olmak üzere her iki webhook sistemindeki son denemeleri gösterir. Olay yükünü, transkripti, saklanan hata metnini, yanıt gövdesini veya URL yolunu asla döndürmez.

Aynı son geçmişi Ajanlar → bir ajan seçin → Webhook'lar → Son teslimatlar bölümünde de görebilirsiniz. Satırlar, uç nokta etiketini ve en son denemede kullanılan URL kaynağını gösterir. Bu, değiştirilemez bir denetim günlüğü yerine operasyonel durumdur: bir uç noktayı silmek, teslimat satırlarını da siler.

Bir n8n 404 hatasında önce iş akışının etkin olduğunu, POST kabul ettiğini ve test URL'si yerine üretim webhook URL'sini kullandığını doğrulayın. 401 veya 403, kimlik doğrulama ya da imza doğrulamasına işaret eder; zaman aşımları hedef gecikmesine veya kullanılabilirliğine; TLS hataları ise sertifika zincirine, ana makine adına ya da sona erme tarihine işaret eder.

İlgili#