---
title: "Webhook'lere Genel Bakış"
description: "ThunderPhone'un gerçek zamanlı olayları nasıl ilettiği, imzaların nasıl doğrulanacağı ve eski model ile uç nokta tabanlı teslim modellerinin nasıl karşılaştırıldığı."
---

ThunderPhone, bir çağrı sırasında gerçekleşen olaylarda — gelen çağrının başlaması, çağrının bitmesi, bir değerlendirme çalışmasının tamamlanması, bir uyarının tetiklenmesi vb. — sunucunuza HTTP `POST` istekleri gönderir. **İki teslim modeli** vardır:

<CardGroup cols={2}>
  <Card title="Webhook uç noktaları (önerilen)" icon="bolt" href="/tr/webhooks/endpoints">
    Birden çok URL, uç nokta başına gizli anahtarlar, uç nokta başına olay filtreleri
    ve otomatik yeniden denemeler.
    `GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints` üzerinden yönetin.
  </Card>
  <Card title="Tek URL'li eski webhook" icon="link" href="/api-reference/organizations#legacy-single-url-webhook">
    Kuruluş başına bir URL. **Bloklayıcı** yapılandırma alışverişleri
    dahil olmak üzere çağrı yaşam döngüsü olaylarını taşır. `GET/PUT /v1/webhook` üzerinden yönetilir.
  </Card>
</CardGroup>

[Olay kataloğunda](/tr/webhooks/events) listelenen tüm olay türleri webhook uç noktaları üzerinden
teslim edilir. Altı çağrı yaşam döngüsü olayı
(`telephony.incoming`, `telephony.complete`, `telephony.tool`,
`web.incoming`, `web.complete`, `web.tool`) **ayrıca** eski tek URL'li
webhook'a da gönderilir — hem eski bir URL'niz hem de eşleşen bir uç noktanız varsa,
olayı **her iki** yolda da alırsınız. Bloklayıcı davranış ([
`telephony.incoming` / `web.incoming` yapılandırma
alışverişi](/tr/webhooks/call-incoming) ve webhook modu
[araç yönlendirmesi](/tr/tools/overview)) yalnızca eski yolda
bulunur; her uç nokta teslimi, yanıt beklemeden gönderilen bir bildirimdir.

## Yük biçimi

Uç nokta teslimleri `data`, `event_id` ve `type` içeren bir JSON nesnesidir:

```json
{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}
```

`event_id`, yayımlanan her olay için benzersizdir. Yeniden denemelerde
**ve** olayı alan her uç noktada aynıdır — tekilleştirme için bunu kullanın.

Eski tek URL'li webhook aynı `type` ve `data` değerlerini ancak
`event_id` **olmadan** gönderir:

```json
{
  "type": "telephony.incoming",
  "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" }
}
```

Aktarım sırasında her gövde kanonik olarak serileştirilir — anahtarlar alfabetik
olarak sıralanır, boşluk kullanılmaz, UTF-8 kullanılır. Bu belgelerdeki okunabilir
biçimlendirilmiş örnekler yalnızca okunabilirlik içindir.

Olay türleri ve yük alanlarının tam listesi için [Olaylar
kataloğuna](/tr/webhooks/events) bakın.

## İmza doğrulama

Her istek, ikisi de uç noktanın `secret` anahtarıyla (veya eski teslimatlar için kuruluş düzeyindeki webhook `secret` anahtarınızla) HMAC-SHA256 kullanılarak oluşturulmuş iki imza taşır:

- `X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex>`, zaman damgasını, yöntemi, yolu ve sorguyu ve ham gövdeyi imzalar. Bunu doğrulayın ve yakalanmış bir isteğin daha sonra yeniden oynatılmasını önlemek için `t` değeri saatinizden **5 dakikadan** fazla farklı olan istekleri reddedin. Yeniden denemeler gönderildiklerinde yeniden imzalanır.
- `X-ThunderPhone-Signature` yalnızca ham gövdeyi imzalar. Mevcut doğrulayıcıların çalışmaya devam etmesi için değişmeden gönderilmeye devam eder.

### Adımlar

1. Ayrıştırmadan **önce** üst bilgiyi, yöntemi, ham yolu ve sorguyu ve ham
   gövdeyi okuyun.
2. Sırrınızı kullanarak
   `<t>\n<METHOD>\n<path and query>\n<body>` öğesinin onaltılık HMAC-SHA256 değerini hesaplayın.
3. `t` 300 saniyeden fazla sapmışsa veya sonuç sabit zamanlı bir karşılaştırmada `v1` ile eşleşmiyorsa
   isteği reddedin.

Gövde, kanonik JSON serileştirmesidir (anahtarlar sıralı, ayırıcılar sıkıştırılmıştır) ve ilettiğimiz baytları tam olarak imzalarız.
[Doğrulama kılavuzu](/tr/guides/verify-webhook-signatures), imzalanan tam dizeyi, uygulamalı bir örneği, SDK olmadan kodu ve eski üst bilgiyi içerir.

<CodeGroup>
```python Python (Flask)
from flask import Flask, abort, request
from thunderphone import verify_signature

app = Flask(__name__)

@app.post("/thunderphone-webhook")
def handle():
    query = request.query_string.decode()
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=WEBHOOK_SECRET,
        method=request.method,
        path=request.path + (f"?{query}" if query else ""),
        body=request.get_data(),  # raw bytes
    ):
        abort(401)
    event = request.get_json()
    # dispatch on event["type"] …
    return "", 204
```

```javascript Node.js (Express)
import express from "express";
import { verifySignature } from "@thunderphone/sdk";

const app = express();
app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ok = verifySignature({
      header: req.header("X-ThunderPhone-Signature-V2"),
      secret: process.env.WEBHOOK_SECRET,
      method: req.method,
      path: req.originalUrl,
      body: req.body,
    });
    if (!ok) return res.sendStatus(401);
    const event = JSON.parse(req.body.toString("utf8"));
    // dispatch on event.type …
    res.sendStatus(204);
  },
);
```
</CodeGroup>

## Teslim semantiği

Bu anlamlar **uç nokta** teslimatları için geçerlidir. Eski tek URL'li
webhook, telefon görüşmesi [`telephony.incoming`](/tr/webhooks/call-incoming)
yapılandırma alışverişi hariç, yeniden denemesi olmayan tek bir eşzamanlı denemedir;
bu alışveriş bir kez yeniden denenir.

<AccordionGroup>
  <Accordion title="Yeniden denemeler">
    Her olay hemen bir kez denenir. Herhangi bir `2xx` yanıtı
    teslimatı onaylar. Diğer tüm sonuçlarda (2xx dışı,
    bağlantı hatası, zaman aşımı), ilk denemeden **1 dk., 5 dk., 30 dk., 2 sa.,
    6 sa., 12 sa. ve 24 sa. sonra** yeniden deneriz — 24 saate yayılan
    8 deneme. Her deneme başarısız olursa teslimat durur ve uç nokta,
    [webhook uç noktaları](/tr/webhooks/endpoints) bölümünde `status="failing"` olarak
    işaretlenir; kuruluşunuzun sahiplerine ve yöneticilerine e-posta gönderir,
    ayrıca bunu kontrol panelinde gösteririz. Yük kalıcı olarak kabul edilir edilmez
    `2xx` döndürün; eşzamansız olarak işleyin.
    Uç nokta test API'sinden yapılan test gönderimleri, ilk denemeden yaklaşık bir
    dakika sonra bir kez yeniden denenir ve uç noktanın durumunu asla değiştirmez.
  </Accordion>

  <Accordion title="Sıralama">
    Teslimat sıralaması en iyi çaba esasına dayanır. Uygulamada olayları
    yayımlandıkları sırayla teslim ederiz, ancak yeniden denemeler başarısızlık
    durumunda sıralamayı değiştirebilir.
    Her zaman `call_id` / nesne kimliğine göre yinelenenleri ayıklayın ve uzlaştırın.
  </Accordion>

  <Accordion title="Yinelenenler">
    Teslimat **en az bir kez** gerçekleşir: görmediğimiz bir yanıttan sonraki
    yeniden deneme bir olayı yineleyebilir. Her yeniden deneme aynı
    `event_id` değerini taşır; bu nedenle işlenen kimlikleri depolayın ve
    tekrarları atlayın. `event_id`, uç noktalar arasında da paylaşılır —
    aynı olaya abone olan iki uç nokta aynı `event_id` değerini alır.
  </Accordion>

  <Accordion title="Zaman aşımları">
    Uç nokta teslimatlarında deneme başına **30 sn.** zaman aşımı vardır. Eski
    yolda, canlı çağrı davranışını yönlendiren engelleyici istekler —
    [`telephony.incoming` / `web.incoming`](/tr/webhooks/call-incoming)
    yapılandırma alışverişi — telefon görüşmesinin ilk denemesi için **10 sn.**,
    tek yeniden deneme dahil tüm alışveriş için **13 sn.** ve bir bileşen
    oturumu için **10 sn.** ile sınırlıdır. Yavaş bir yanıt çağrının
    cevaplanmasını geciktirir; bu nedenle birkaç saniye içinde yanıt vermeyi hedefleyin. Webhook modundaki [araç gönderimi](/tr/tools/overview) varsayılan olarak 20 sn.
    tanır ve araç bildirimleri üst düzey bir `timeout` ayarlayabilir.
  </Accordion>

  <Accordion title="Kaynak IP'ler">
    Giden webhook'lar ThunderPhone'ın bulut IP aralığından kaynaklanır.
    Güvenlik duvarınız izin listesi gerektiriyorsa destek ekibiyle iletişime geçin;
    güncel aralıkları paylaşırız.
  </Accordion>
</AccordionGroup>

## Eski ve uç nokta tabanlı webhook'lar arasında seçim yapma

| Özellik | Eski (`/v1/webhook`) | Uç noktalar (`/v1/developer/webhook-endpoints`) |
|---------|------------------------|----------------------------------------------|
| URL sayısı | Kuruluş başına 1 | Kuruluş başına çok sayıda |
| Etkinlik kapsamı | Yalnızca `telephony.*` / `web.*` | 10 etkinlik türünün tamamı |
| Etkinlik filtresi | — | Uç nokta başına |
| Yeniden denemeler | Telefon araması yapılandırma alışverişi için bir deneme dışında yok | 24 saat içinde 8 deneme |
| Zarf | `type` + `data` | `type` + `data` + `event_id` |
| Gizli anahtar rotasyonu | Tek gizli anahtarı değiştirir | Uç nokta başına gizli anahtar |
| Silmeden devre dışı bırakma | `{"url": ""}` ile `PUT /v1/webhook` | `status=disabled` |
| Durum görünürlüğü | — | `active` / `disabled` / `failing` |
| Engelleyici yapılandırma alışverişi | Evet ([`telephony.incoming` / `web.incoming`](/tr/webhooks/call-incoming)) | Asla — yalnızca bildirimler |
| En uygun kullanım | Dinamik arama yapılandırması | Üretimde etkinlik tüketimi |

Yeni entegrasyonlar, olayları uç nokta tabanlı webhook'lar aracılığıyla
tüketmelidir. Yalnızca çağrıları yanıtlanma anında dinamik olarak
yapılandırıyorsanız veya webhook modunda araç yönlendirme kullanıyorsanız
eski bir URL'yi koruyun (veya ekleyin) — bu istek/yanıt alışverişleri
yalnızca eski yolda çalışır.

---

## İlgili

<CardGroup cols={2}>
  <Card title="Etkinlik kataloğu" icon="list" href="/tr/webhooks/events">
    Tüm etkinlik türleri ve yükleri.
  </Card>
  <Card title="Webhook uç noktaları" icon="bolt" href="/tr/webhooks/endpoints">
    Birden fazla uç noktayı, etkinlik filtresini ve gizli anahtarı yönetin.
  </Card>
  <Card title="telephony.incoming / web.incoming" icon="phone" href="/tr/webhooks/call-incoming">
    Aramaları yapılandırmak için sunucunuzun yanıtlaması gereken engelleyici istek.
  </Card>
  <Card title="telephony.complete / web.complete" icon="phone" href="/tr/webhooks/call-complete">
    Transkript, kayıt ve metrikleri içeren arama sonrası yük.
  </Card>
</CardGroup>