--- title: "Webhook Uç Noktaları" description: "Uç nokta başına gizli anahtarlar ve olay filtreleriyle birden fazla webhook URL'sini yönetin." --- 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](/api-reference/organizations#legacy-single-url-webhook) ile karşılaştırın. ## Uç Noktalar | Yöntem | Yol | Gerekli rol | Açıklama | |--------|------|---------------|-------------| | `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Uç noktaları listeleyin | | `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Uç nokta oluşturun | | `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Etiketi / URL'yi / etkinlikleri / durumu güncelleyin | | `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Uç noktayı silin | | `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret` | `admin+` | İmzalama gizli anahtarını değiştirin | | `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | İmzalı bir test teslimatı gönderin | | `GET` | `/v1/developer/webhook-deliveries` | `admin+` | Son uç nokta ve eski teslimat sonuçlarını inceleyin | ## Uç nokta nesnesi ```json { "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" } ``` | 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ğerler](#valid-event-types) bölümüne bakın). Boş dizi, yalnızca açıkça belirtilerek abone olunabilen tur başına etkinlikler (`telephony.turn` / `web.turn`) dışındaki tüm etkinliklere abone olur | | `status` | string | `active`, `disabled` (manuel olarak duraklatılmış) veya `failing` (bir teslimat, tek bir 2xx yanıtı almadan 24 saatlik yeniden deneme planını tükettiğinde otomatik olarak ayarlanır) | | `agent_id` | integer \| null | Bu uç noktanın kapsamındaki ajan; `null`, kuruluş genelini belirtir | | `agent_name` | string \| null | Kapsamdaki ajanın adı veya kuruluş genelindeki uç nokta için `null` | | `secret_hint` | string | İmzalama gizli anahtarının ilk 4 ve son 4 karakteri, arada üç nokta olacak şekilde (`a1b2…9f0e`) — tam değeri göstermeden yerel olarak kaydettiğiniz gizli anahtarla karşılaştırmanız için yeterlidir | | `paused_at` | timestamp \| null | ThunderPhone'un uç noktayı `failing` olarak ayarladığı zaman. `active` veya `disabled` durumundayken `null` | | `pause_last_error` | string | Uç nokta duraklatıldığındaki son teslimat hatası; örneğin `HTTP 503: Service Unavailable`. `failing` olmadığı sürece boştur | | `pause_undelivered_count` | integer \| null | Uç noktanın son başarılı teslimatından bu yana teslim edilmeyen etkinlikler; duraklatıldığında sayılır | | `created_at`, `updated_at` | timestamp | | Uç noktanın tam `secret` değeri oluşturma sırasında **yalnızca bir kez** döndürülür ve bir daha asla döndürülmez. Güvenli bir şekilde saklayın — kaybederseniz yenisini almak için [değiştirin](#rotate-the-signing-secret). ### 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](/tr/webhooks/events) 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 ```bash cURL curl https://api.thunderphone.com/v1/developer/webhook-endpoints \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` [Uç nokta nesneleri](#endpoint-object) 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 ```bash cURL 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"] }' ``` ```python Python 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ılması veya belirtilmemesi, açık abonelik gerektiren `telephony.turn` / `web.turn` dışındaki tüm olaylara abone olur. [Geçerli olay türleri](#valid-event-types) bölümünde listelenen değerler kullanılmalıdır; yinelenenler kaldırılır | | `agent_id` | tamsayı \| null | hayır | Teslimatı bu kuruluştaki bir ajanla sınırlayın; kuruluş genelindeki bir uç nokta için bu alanı atlayın veya `null` kullanın | [Uç nokta nesnesi](#endpoint-object) 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: ```json { "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öndürülür. Sonraki `GET` yanıtları yalnızca `secret_hint` içerir. Yanıtı kapatmadan önce tam değeri gizli anahtar yöneticinize kopyalayın. --- ## Bir uç noktayı güncelleyin ```bash cURL 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` değerini ayarlayın | | `agent_id` | tamsayı \| null | Uç noktayı sınırlamak için bir ajan kimliği, kuruluş genelinde yapmak için ise `null` ayarlayın | Güncellenmiş [uç nokta nesnesi](#endpoint-object) 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. ```bash cURL 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 '{}' ``` | Alan | Tür | Zorunlu | Açıklama | |-------|------|----------|-------------| | `include_copies` | boolean | hayır | Varsayılan değer `true`. Ayrıca, diğer ajanlardaki bu uç noktanın kopyaları gibi aynı URL'ye ve aynı geçerli gizli anahtara sahip kuruluşunuzdaki diğer uç noktalara da yeni gizli anahtarı verir; böylece bir alıcı tek bir gizli anahtarla doğrulamayı sürdürür | `200 OK` döndürür: ```json { "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." }, "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d", "rotated_endpoint_ids": ["c4d5e6f7-..."] } ``` | Alan | Tür | Açıklama | |-------|------|-------------| | `endpoint` | object | Yeni `secret_hint` değeriyle [Uç nokta nesnesi](#endpoint-object) | | `secret` | string | Yeni imzalama gizli anahtarı. Yalnızca bu yanıtta döndürülür | | `rotated_endpoint_ids` | UUID dizisi | Artık yeni gizli anahtarı kullanan her uç nokta | Eski gizli anahtarın kullanımı hemen durur: yeniden denemeler dahil sonraki teslimat, yeni gizli anahtarla imzalanır. Alıcınız yeni gizli anahtara sahip olana kadar teslimatlar imza denetiminde başarısız olur; alıcınız bunlara 2xx olmayan bir durumla yanıt verirse normal 24 saatlik zamanlamaya göre yeniden denenir. Bu nedenle alıcıyı hemen güncelleyin. Alıcınız aşamalı olarak yayına alınıyorsa, yayına alma sırasında her iki gizli anahtarı da kabul etmesini sağlayın — SDK doğrulama yardımcıları bir gizli anahtar listesi alır (bkz. [Webhook imzalarını doğrulama](/tr/guides/verify-webhook-signatures)). --- ## 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. ```bash cURL 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: ```json { "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: ```json { "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ı](#debug-deliveries) 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. ```bash 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](#valid-event-types) içindeki herhangi bir değeri kabul eder. Bu alanı atlamak, genel `webhook.test` davranışını korur. --- ## Uç noktayı silin ```bash cURL 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`](/api-reference/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 Abone olabileceğiniz tüm `events` değerlerinin listesi. İmza doğrulama ve teslimat anlamları.