# Webhooks API

Webhooks, yeni bir kişi, bir yanıt, rezerve edilen bir randevu ve daha fazlası gibi bir şey gerçekleştiği anda platformun diğer sistemlerinizi bilgilendirmesini sağlar. Bu API, **aboneliklerin** kendisini yönetir: hangi URL'lerin hangi olayları alacağını belirler. Uç noktanızın aldığı yükleri (payloads) nasıl alacağınız ve doğrulayacağınız hakkında bilgi için [Webhooks](../integrations/webhooks.md) bölümüne bakın.

Aşağıdaki tüm yollar, API temel URL'sine göre belirlenmiştir:

```
https://api.youraiconnector.com/v1
```

Her isteğin kimliği doğrulanmalıdır. Kabul edilen dört yöntem için [Kimlik Doğrulama](authentication.md) bölümüne bakın. Buradaki örnekler `X-API-Key` başlığını (ve cURL için bir sorgu parametresi biçimini) kullanır.

::: note
**Not:** Webhook'lar hesabınız için etkinleştirilmiş olmalıdır. Etkinleştirilmemişlerse, bu uç noktalar bir `403` döndürür.
:::


---

## Abonelikler nasıl adreslenir

Her aboneliğin bir `id` ve isteğe bağlı bir `name` değeri vardır. Her ikisi de güncelleme, silme, test, sağlık durumu ve yeniden etkinleştirme yollarında `{webhookId}` olarak kullanılabilir.

> **İsmi tercih edin.** Abonelik kimlikleri konumsal olduğundan, başka bir abonelik silindikten sonra değişebilirler. Bir abonelik oluştururken sabit bir `name` ayarlarsanız, sürprizlerden kaçınmak için ona ismiyle hitap edin.

---

## Abonelikleri listele

`GET /webhooks`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Yanıt**

```json
{
  "success": true,
  "webhooks": [
    {
      "id": "0",
      "name": "Order updates hook",
      "url": "https://hooks.example.com/incoming",
      "subscribed_to": ["Contact Created", "Replies"],
      "subscribed_to_tags": [],
      "created_at": "2026-06-09T12:00:00.000Z",
      "signing_enabled": true,
      "signing_secret_created_at": "2026-07-15T09:30:00.000Z",
      "retries_enabled": true,
      "enabled": true,
      "apply_to_sub_accounts": false
    }
  ]
}
```

`signing_enabled` ve `retries_enabled` abonelik bazlı isteğe bağlı özelliklerdir ve siz açmadığınız sürece her ikisi de kapalıdır. Bkz. [İmzalı yükler](#signed-payloads) ve [Yeniden denemeler](#retries).

`apply_to_sub_accounts`, ajans-mirası katılımıdır — bkz. [Tüm müşteri hesapları için tek abonelik](#one-subscription-for-all-client-accounts-agencies). Varsayılan olarak kapalıdır ve müşteri hesabı olmayan hesaplarda etkisizdir.

`enabled`, aboneliğin açma/kapama anahtarıdır — bkz. [Bir aboneliği kapatma](#switching-a-subscription-off). Kapatılan abonelikler burada listelenmeye devam eder.

İmzalama gizli anahtarının kendisi burada asla yer almaz — onu [`GET /webhooks/{id}/signing-secret`](#read-the-signing-secret) adresinden okuyun.

---

## Abone olunabilir olay türlerini listele

`subscribed_to` içinde kullanabileceğiniz tam dizeleri döndürür. Bunu, olay adlarını kodunuza sabit olarak yazmak yerine geçerli olay adlarını keşfetmek için kullanın.

`GET /webhooks/events`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/webhooks/events" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/events", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks/events",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Yanıt**

Yanıt `{"success": true, "events": [...]}` şeklindedir ve `events` şu anda 22 kesin dizeyi barındırır: Contact Created, Human Alerted, Appointment Booked, Replies, Reads, Deliveries, Credits Spent, Credits Recharged, Low Credit Balance, Contact Paused, Contact Do Not Disturb, Contact Unarchived, New Message, Contact Resumed, Chat Concluded, Task Created, Task Updated, Task Completed, Daily Summary Created, Channel Connected, Broadcast Started ve Broadcast Completed (Channel Connected, `subscribed_to` içinde kabul edilir ancak şu anda hiçbir şey bunu yaymaz, bu yüzden buna göre geliştirme yapmayın).

Her bir olayın ne anlama geldiği ve yükte (payload) hangi `event` kodunu gönderdiği hakkında bilgi için bkz. [22 Webhook Olayı](../integrations/webhooks.md#the-22-webhook-events). Bu uç nokta her an için yetkili listedir; isimleri kodunuza sabit olarak yazmak yerine canlı olarak okuyun.

---

## Bir abonelik oluştur

`POST /webhooks`

| Alan | Gerekli | Açıklama |
|---|---|---|
| `url` | Evet | Etkinlik yüklerini `POST` aracılığıyla alacak HTTPS URL'si. Herkese açık şekilde erişilebilir olmalıdır. |
| `subscribed_to` | Evet | Etkinlik adlarından oluşan boş olmayan bir dizi (bkz. `/webhooks/events`). |
| `name` | Hayır | Bir görünen ad. Daha sonra `{webhookId}` olarak da kullanılabilir. Varsayılan olarak zaman damgalı bir ad kullanılır. |
| `subscribed_to_tags` | Hayır | Hangi etiketlerin konuşma özeti bildirimi oluşturacağını daraltan etiket kimlikleri. Bu, aboneliğin etkinliklerini bu etiketlerle sınırlamaz; belirli bir etiket uygulandığında istek almak için, temsilcinin (veya kampanyanın) **Etiketler** sekmesindeki etikete bir webhook URL'si ayarlayın. |
| `retries_enabled` | Hayır | Boole değeri, varsayılan `false`. Başarısız teslimatların [yeniden denenmesi](#retries) için katılım sağlayın. |
| `generate_signing_secret` | Hayır | Boole değeri, varsayılan `false`. Abonelikle birlikte bir HMAC [imzalama gizli anahtarı](#signed-payloads) oluşturun. Gizli anahtar, yanıtta üst düzey bir `signing_secret` olarak bir kez döndürülür. |
| `enabled` | Hayır | Boole değeri, varsayılan `true`. Aboneliği kapalı olarak oluşturmak için `false` değerini iletin. Bkz. [Aboneliği kapatma](#switching-a-subscription-off). |
| `apply_to_sub_accounts` | Hayır | Boole değeri, varsayılan `false`. Bir ajans hesabında `true`, bu aboneliğin tüm müşteri hesaplarından da etkinlik almasını sağlar — bkz. [Tüm müşteri hesapları için tek abonelik](#one-subscription-for-all-client-accounts-agencies). |

> **URL kuralları:** URL, `https://` kullanmalı ve herkese açık şekilde erişilebilir olmalıdır. Düz `http://`, `localhost`, özel ağ adresleri ve platform içi adresler `400` ile reddedilir.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Order updates hook"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Order updates hook",
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Order updates hook",
    },
)
data = res.json()
```

**Yanıt**

```json
{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Order updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}
```

---

## Bir aboneliği güncelle

`url`, `subscribed_to`, `name`, `subscribed_to_tags`, `retries_enabled`, `enabled` veya `apply_to_sub_accounts` alanlarından en az birini sağlayın. Atlanan alanlar mevcut değerlerini korur. `subscribed_to` ve `subscribed_to_tags` birleştirme değil, değiştirme işlemidir.

`PUT /webhooks/{webhookId}`

> Bir aboneliği güncellemek, imzalama gizli anahtarını asla bozmaz — bunu [imzalama gizli anahtarı rotaları](#signed-payloads) üzerinden yönetin.

> URL değiştiğinde, yeni URL için teslimat otomatik olarak yeniden etkinleştirilir ve daha önce başarısız olan bir uç noktaya temiz bir başlangıç sağlar.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/Order%20updates%20hook" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/v2/incoming",
    "subscribed_to": ["Replies", "Chat Concluded"]
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  `https://api.youraiconnector.com/v1/webhooks/${encodeURIComponent("Order updates hook")}`,
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://hooks.example.com/v2/incoming",
      subscribed_to: ["Replies", "Chat Concluded"],
    }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/webhooks/Order updates hook",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://hooks.example.com/v2/incoming",
        "subscribed_to": ["Replies", "Chat Concluded"],
    },
)
data = res.json()
```

**Yanıt**

```json
{
  "success": true,
  "webhook_id": "0",
  "webhook": {
    "id": "0",
    "name": "Order updates hook",
    "url": "https://hooks.example.com/v2/incoming",
    "subscribed_to": ["Replies", "Chat Concluded"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}
```

Bilinmeyen bir kimlik veya ad, `{ "success": false, "error": "Webhook not found" }` ile birlikte `404` döndürür.

---

## Bir aboneliği sil

Aboneliği kaldırır, böylece URL'si artık yük almaz. Teslimat sağlığı sayaçları sıfırlanır, bu nedenle aynı URL'yi daha sonra tekrar eklemek temiz bir kayıtla başlar.

`DELETE /webhooks/{webhookId}`

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/webhooks/0",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Yanıt**

```json
{
  "success": true
}
```

---

## Bir test yükü gönder

Alıcınızı uçtan uca doğrulayabilmeniz için aboneliğin URL'sine örnek bir yük gönderir. Örnekle hangi etkinlik türünün simüle edileceğini kontrol etmek için isteğe bağlı olarak bir `event` iletin. Test teslimatları, aboneliğin sağlık sayaçlarını asla etkilemez.

`POST /webhooks/{webhookId}/test`

Yanıt her zaman `200` döndürür ve sonucu bir `delivered` bayrağıyla bildirir; başarısız bir test hata durumu döndürmez. `delivered` değeri `false` olduğunda, yanıt hata ayrıntılarını içerir.

| Alan | Zorunlu | Açıklama |
|---|---|---|
| `event` | Hayır | Simüle edilecek etkinlik türü (`/webhooks/events` değerlerinden biri olmalıdır). Varsayılan olarak bir teslimat etkinliğidir. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/test?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "Contact Created" }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/test", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ event: "Contact Created" }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks/0/test",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"event": "Contact Created"},
)
data = res.json()
```

**Yanıt** (iletildi)

```json
{
  "success": true,
  "webhook_id": "0",
  "delivered": true
}
```

**Yanıt** (başarısız)

```json
{
  "success": true,
  "webhook_id": "0",
  "delivered": false,
  "failure_type": "permanent",
  "status_code": 404,
  "error_message": "Request failed with status code 404"
}
```

`failure_type`; `permanent`, `temporary`, `timeout`, `network` veya `unknown` değerlerinden biridir.

---

## Teslimat durumunu kontrol et

Aboneliğin URL'si için teslimat durumu kaydını döndürür: kaç teslimatın başarılı ve başarısız olduğu, tekrarlanan hatalardan sonra teslimatın şu anda duraklatılıp duraklatılmadığı ve en son hatanın ayrıntıları. Henüz hiçbir teslimat denenmediğinde `"health": null` döndürür.

`GET /webhooks/{webhookId}/health`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/webhooks/0/health" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/health", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks/0/health",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Yanıt**

```json
{
  "success": true,
  "webhook_id": "0",
  "url": "https://hooks.example.com/incoming",
  "health": {
    "consecutive_failures": 0,
    "total_failures": 2,
    "total_successes": 120,
    "is_disabled": false,
    "disabled_at": null,
    "disabled_reason": null,
    "last_failure": null,
    "last_success_at": "2026-06-09T12:00:00.000Z",
    "created_at": "2026-05-01T08:00:00.000Z",
    "updated_at": "2026-06-09T12:00:00.000Z"
  }
}
```

`is_disabled` değeri `true` olduğunda, URL'ye yapılan teslimat tekrarlanan hatalardan sonra otomatik olarak duraklatılmıştır. Alıcınızı düzeltin ve ardından (aşağıdan) yeniden etkinleştirin.

---

## Teslimatı yeniden etkinleştir

URL'si tekrarlanan hatalardan sonra otomatik olarak duraklatılan bir webhook için teslimatı sürdürür. Bu işlem, duraklatma bayrağını ve hata sayaçlarını sıfırlar ancak bir teslimat denemesi **yapmaz**; alıcınızın tekrar sağlıklı olduğunu doğrulamak için sonrasında test uç noktasını kullanın.

`POST /webhooks/{webhookId}/reenable`

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/reenable?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/reenable", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks/0/reenable",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Yanıt**

```json
{
  "success": true,
  "webhook_id": "0"
}
```

---

## Bir aboneliği kapatma

`enabled`, aboneliğin kendi açma/kapama anahtarıdır. Kapatılması, URL'yi, etkinlik listesini ve imzalama gizli anahtarını korurken teslimatları durdurur.

```bash
# Off
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Back on
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

- **Belirtilmemesi açık olduğu anlamına gelir.** Bu alan mevcut olmadan önce oluşturulan bir aboneliğin kayıtlı `enabled` değeri yoktur ve normal şekilde teslimat yapar. `GET /webhooks` her zaman somut bir boole değeri bildirir.
- Kapatılan abonelikler `GET /webhooks` tarafından **listelenmeye devam eder** — onları tekrar açmak için bu şekilde bulursunuz.
- Kapatma işleminden önce kuyruğa alınan bir [yeniden deneme](#retries) devam etmez: yeniden deneme, gönderim sırasında aboneliği tekrar okur ve kapalıysa işlemi bırakır.
- Kapalıyken engellenen hiçbir şey, tekrar açtığınızda yeniden oynatılmaz.

> Tekrarlanan başarısızlıklar sonrasında gerçekleşen otomatik devre dışı bırakma işleminden farklıdır; bu durum [`GET /webhooks/{id}/health`](#check-delivery-health) tarafından `is_disabled` olarak bildirilir ve [`POST /webhooks/{id}/reenable`](#re-enable-delivery) ile temizlenir. `enabled` hesabın anahtarıdır; `is_disabled` ise bizimkidir. Hiçbiri diğerini geçersiz kılmaz; bir aboneliğin teslimat yapabilmesi için hem açık olması hem de otomatik olarak devre dışı bırakılmamış olması gerekir.

---

## Tüm müşteri hesapları için tek abonelik (ajanslar)

Bir ajans hesabında, bir abonelikte (oluşturma sırasında veya `PUT` aracılığıyla) `apply_to_sub_accounts: true` ayarını yapın; böylece abonelik, ajansın tüm müşteri hesaplarında gerçekleşen olayları da alır — her müşteri hesabında aboneliği yeniden oluşturmak yerine, tüm ajansı kapsayan tek bir uç nokta yeterlidir.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apply_to_sub_accounts": true}'
```

Nasıl çalışır:

- **`user` bloğu hesapları birbirinden ayırır.** Her yükün `user` bloğu, olayın gerçekten hangi hesapta gerçekleştiğini tanımlar, böylece alıcınız müşteri bazlı yönlendirme yapabilir.
- **Ajans aboneliğinin kendi ayarları her yerde geçerlidir.** Olay listesi, [imzalama gizli anahtarı](#signed-payloads) ve [yeniden deneme](#retries) katılımı, devralınan teslimatlar için de kullanılır.
- **Müşteri hesabının aynı URL'ye olan kendi aboneliği önceliklidir.** Bir müşteri hesabının aynı URL'yi işaret eden kendi aboneliği varsa, o hesabın olayları için bu abonelik kullanılır; aynı olay bir uç noktaya asla iki kez teslim edilmez.
- **Müşteri hesapları bunu görmez.** Devralınan abonelikler, müşteri hesabının kendi webhook listesinde görünmez ve müşteri bunları kapatamaz; yalnızca ajans bunları yönetir.
- **Teslimat sağlığı müşteri hesabı bazında izlenir.** Sürekli başarısız olan bir uç nokta, tüm ajans için değil, yalnızca teslimatları başarısız olan hesap için otomatik olarak devre dışı bırakılır.
- **`subscribed_to_tags` devralınmaz.** Etiket listesi, müşteri hesaplarında bulunmayan ajansın kendi etiketlerine referans verir; konuşma özeti daraltma yalnızca ajansın kendi olayları için geçerlidir.
- **Başka yerlerde etkisizdir.** Müşteri hesabı olmayan bir hesapta bayrak düzgün bir şekilde saklanır ancak hiçbir işlev görmez.

---

## Her teslimatta bulunan başlıklar

Bu üç başlık, aboneliğin imzalı olup olmadığına bakılmaksızın her teslimatta gönderilir:

| Başlık | Anlamı |
|---|---|
| `X-Webhook-Delivery` | Mantıksal olay için kararlı kimlik. Yeniden denemeler boyunca aynıdır; bunun üzerinden tekilleştirme yapın. |
| `X-Webhook-Attempt` | 1 tabanlı deneme numarası. |
| `X-Webhook-Event` | Olay adı. |

---

## İmzalı yükler

İmzalama isteğe bağlıdır, varsayılan olarak kapalıdır ve abonelik başına ayarlanır. Bir aboneliğin imzalama gizli anahtarı olduğunda, her teslimat, her teslimatta gönderilen üç başlığa (`X-Webhook-Delivery`, `X-Webhook-Attempt` ve `X-Webhook-Event`) ek olarak iki başlık daha taşır:

| Başlık | Anlamı |
|---|---|
| `X-Webhook-Signature` | `v1=<hex>` — `GET/POST/DELETE /v1/webhooks/{webhookId}/signing-secret` adresinde oluşturduğunuz ve döndürdüğünüz webhook başına imzalama gizli anahtarı ile anahtarlanmış, `"<timestamp>.<raw request body>"` dizesinin HMAC-SHA256 değeri. |
| `X-Webhook-Timestamp` | Gönderim zamanı, Unix saniyeleri. İmzaya dahil edilmiştir, bu nedenle bağımsız olarak değiştirilemez. |

Doğrulamak için, ham gövde üzerinde gizli anahtarınızla HMAC-SHA256'yı yeniden hesaplayın ve başlıkla karşılaştırın. **Ham** istek gövdesine göre doğrulama yapın. Ayrıştırılmış JSON'u yeniden serileştirmek baytları değiştirir ve karşılaştırmayı bozar. Tekrar saldırılarını (replay) önlemek için zaman damgası bir tazelik penceresinin (300 saniye makul bir varsayılandır) dışında olan teslimatları reddedin ve zamanlama açısından güvenli bir fonksiyonla karşılaştırın.

Tam Node ve Python doğrulama örnekleri için [İmzalı Yükler](../integrations/webhooks.md#signed-payloads-verifying-a-webhook-really-came-from-us) bölümüne bakın.

> **İmzalama, API kimlik doğrulaması ile aynı şey değildir.** REST API'nin kendisi OAuth yerine API anahtarlarıyla kimlik doğrulaması yapar (bot araçları olarak kaydettiğiniz MCP sunucuları için OAuth 2.1 mevcuttur) ve henüz resmi bir npm veya PyPI SDK paketi yoktur; uç noktaları herhangi bir HTTP istemcisiyle çağırın.

### İmzalama gizli anahtarını okuyun

`GET /webhooks/{id}/signing-secret`

```bash
curl "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
```

**Yanıt**

```json
{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": true,
  "signing_secret": "whsec_1a2b3c...",
  "signing_secret_created_at": "2026-07-15T09:30:00.000Z"
}
```

İmzalama kapalı olduğunda, `signing_enabled` değeri `false` ve `signing_secret` değeri `null` olur.

### İmzalama gizli anahtarını oluşturun veya döndürün

`POST /webhooks/{id}/signing-secret`

Bir gizli anahtar oluşturur (imzalamayı açar) veya mevcut olanı değiştirir. Yeni gizli anahtarı döndürür.

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
```

**Yanıt**

```json
{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": true,
  "signing_secret": "whsec_9f8e7d...",
  "signing_secret_created_at": "2026-07-15T10:00:00.000Z"
}
```

Döndürme işlemi hemen geçerli olur; bir sonraki teslimat yalnızca yeni gizli anahtarla imzalanır. Değişikliği canlı bir uç noktaya yayarken her iki gizli anahtarı da kısa bir süreliğine kabul edin.

`POST /webhooks` öğesine `"generate_signing_secret": true` değerini geçirerek oluşturma sırasında bir gizli anahtar da oluşturabilirsiniz; yanıt daha sonra üst düzey bir `signing_secret` alanı içerir.

### İmzalamayı kapatma

`DELETE /webhooks/{id}/signing-secret`

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
```

**Yanıt**

```json
{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": false
}
```

> Her üç imzalama gizli anahtarı rotası da `GET` dahil olmak üzere Entegrasyonlar **düzenleme** izni gerektirir; gizli anahtar, teslimatları taklit edebilen bir kimlik bilgisi olduğundan salt okunur rollere gösterilmez.

---

## Yeniden denemeler

İsteğe bağlıdır, varsayılan olarak kapalıdır ve `POST /webhooks` veya `PUT /webhooks/{id}` üzerindeki `retries_enabled` boole değeri aracılığıyla abonelik başına ayarlanır.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"retries_enabled": true}'
```

Etkinleştirildiğinde, başarısız bir teslimat ilk denemeden sonra **1dk, 5dk, 30dk ve 2sa** aralıklarla yeniden denenir (yaklaşık 2 saat 40 dakikalık bir kapsama alanı).

- **Yeniden denenenler:** 5xx yanıtları, zaman aşımları ve bağlantı hataları.
- **Yeniden denenmeyenler:** herhangi bir 4xx. Alıcı isteğin kendisini reddediyorsa, isteği değiştirmeden tekrar oynatmak yalnızca reddi tekrarlar.

Yeniden denemeler mükerrer teslimatı mümkün kılar — bir olayı işleyen ancak yanıt vermeden önce zaman aşımına uğrayan bir uç nokta, olayı tekrar görecektir. Denemeler boyunca sabit kalan `X-Webhook-Delivery` üzerinden tekilleştirme yapın. Yeniden denemelerin isteğe bağlı olmasının nedeni budur.

[delivery-health](#check-delivery-health) sayaçları her denemeyi değil, tüm teslimatı sayar: bir hata yalnızca tüm yeniden denemeler tükendiğinde bir kez kaydedilir, bu nedenle yeniden denemeleri etkinleştirmek otomatik devre dışı bırakma tetikleyicisinin daha erken çalışmasına neden olmaz.

---

## Hatalar

Tüm hatalar standart zarfı kullanır:

```json
{
  "success": false,
  "error": "Webhook not found"
}
```

Yaygın durumlar: izin verilmeyen bir URL, boş/geçersiz bir `subscribed_to` veya eksik alanlar `400` döndürür; bilinmeyen bir kimlik veya ad `404` döndürür; ve `403`, hesabınız için webhook'ların etkinleştirilmediği anlamına gelir. Tam liste için [Hatalar](errors-and-pagination.md) bölümüne bakın.

---

## Sonraki adımlar

- [Web kancaları (yükleri alma)](../integrations/webhooks.md) — alıcınızı ayarlayın ve yük biçimini anlayın.
- [Kimlik Doğrulama](authentication.md) — bir isteğin kimliğini doğrulamanın dört yolu.
- [Hatalar ve Hız Sınırları](errors-and-pagination.md) — durum kodları ve 300 istek/dakika sınırı.