# Webhook'lar

> Webhook abonelikleri, imzanın doğrulanması, yeniden denemeler, KVKK konuları ve özel gövdeli konular (shop/update, müşteriler, pazarlama izni, SMS ve İYS).

Platform, mağazada bir şey değiştiğinde uygulamanın adresine bir `POST` gönderir. Konuların tamamı ve izinleri: [Webhook konuları](../reference/webhook-topics.md).

## Abonelik

Abonelikler `biticaret.app.toml` dosyasındadır ve kurulumda kaydedilir; her kod takası kurulumun aboneliklerini sürümdekilerle değiştirir.

```toml
[[webhooks.subscriptions]]
topics = ["app/uninstalled"]
uri = "/webhooks/app-uninstalled"
```

Bir konu yalnızca iznini taşıyan kurulumlara gider; yapılandırmadaki bir konunun izni `access_scopes` içinde olmalıdır. Adresler HTTPS olmalıdır.

## İstek

```http
POST /webhooks/orders-paid HTTP/1.1
Content-Type: application/json
X-Biticaret-Topic: orders/paid
X-Biticaret-Store-Id: 1000000000001
X-Biticaret-Store-Domain: acme.localhost
X-Biticaret-Event-Id: 01929f8a-7c10-…
X-Biticaret-Triggered-At: 2026-10-18T10:00:00Z
X-Biticaret-Api-Version: 2026-10
X-Biticaret-Hmac-Sha256: …
X-Biticaret-Signature: t=1792317600,v1=…
```

`X-Biticaret-Event-Id` olay başınadır: her abonelik, her yeniden deneme ve her yeniden gönderim için aynıdır. Aynı olay iki kez gelebilir; işleyiciniz ikinci kez çalıştığında bir şey bozmamalıdır.

Mağazayı gövdedeki `store_id` ile bulun. Alan adı değişebilir.

## İmza

Bir webhook iki imza taşır:

- `X-Biticaret-Hmac-Sha256`: ham gövdenin, geçerli gizli anahtarla base64 HMAC-SHA256'sı. Yalnızca gövdeyi kapsar.
- `X-Biticaret-Signature: t=<bu denemenin unix saniyesi>,v1=<base64 HMAC-SHA256>`: başlıkları da kapsar. Anahtar yenilenirken her anahtar için bir `v1` taşır. Tam olarak şu baytlar üzerinde hesaplanır:

  ```
  t=<t>
  event_id=<X-Biticaret-Event-Id>
  topic=<X-Biticaret-Topic>
  store_domain=<X-Biticaret-Store-Domain>
  triggered_at=<X-Biticaret-Triggered-At>
  api_version=<X-Biticaret-Api-Version>

  <ham gövde>
  ```

  Altı `ad=değer` satırı, bir boş satır, sonra ham gövde.

İkincisini denetleyin: konuyu ve mağazayı da bağladığı için, yakalanmış bir `orders/paid` isteği başka bir adresinize yeniden oynatılamaz. `t` şimdiden 5 dakikadan uzaksa reddedin; anahtarlarınızdan biriyle eşleşen herhangi bir `v1` yeterlidir. Tek konuya hizmet eden bir adres, imzalı konu kendi konusu değilse isteği kötü imza gibi `401` ile reddetmelidir.

Go'da bunu `appsdk.VerifyWebhookTopic` yapar: [Go SDK](go-sdk.md#webhook-dogrulamak).

## Teslim ve yeniden deneme

- 5 saniye içinde gelen bir `2xx` teslim sayılır (`store/redact` için 25, `iys/consent` için 20 saniye). Uzun işi kuyruğa alın, hemen yanıtlayın.
- Aksi halde platform yeniden dener: toplam 8 deneme, yaklaşık 4 saat. Denemeler arasındaki beklemeler 1, 5, 10 ve 30 dakika, sonra 1 saat, 1 saat ve 75 dakikadır. Sekizinciden sonra teslim başarısız sayılır.
- **Devre kesici.** Bir aboneliğe art arda 10 başarısız teslimden sonra o abonelik 15 dakika bekletilir: bu sürede yeni teslimler denenmez, devre kapanınca gönderilir ve bekleme denemelerden düşmez. İlk `2xx` sayacı sıfırlar.
- Uygulama kaldırıldıktan sonra bekleyen teslimler başarısız sayılır; `app/uninstalled` yine gönderilir.

## Teslim kaydı ve yeniden gönderim

Uygulama kendi teslim kaydını okur ve bir teslimi yeniden gönderir:

```http
GET /api/v1/webhook_deliveries
POST /api/v1/webhook_deliveries/{id}/replay
```

Kayıt her teslimin durumunu (`pending`, `delivered`, `failed`), deneme sayısını, yanıt kodunu ve süresini 30 gün tutar; gövde 7 gün tutulur, yani bir teslim 7 gün içinde yeniden gönderilebilir. Yeniden gönderim aynı `X-Biticaret-Event-Id` ile yeni bir teslimdir.

## KVKK konuları

Her uygulama üç adresi yanıtlamak zorundadır; bunlar abonelik değildir, `[privacy]` altında yazılır ve izin istemez:

```toml
[privacy]
customers_data_request_url = "/privacy/customers-data-request"
customers_redact_url = "/privacy/customers-redact"
store_redact_url = "/privacy/store-redact"
```

| Konu | Ne ister |
| :--- | :--- |
| `customers/data_request` | Bir müşteri hakkında tuttuğunuz veriyi bildirin. |
| `customers/redact` | Bir müşteri hakkında tuttuğunuz veriyi silin. |
| `store/redact` | Bir mağaza hakkında tuttuğunuz her şeyi silin. |

`store/redact`, uygulama kaldırıldıktan 30 gün sonra, yalnızca o uygulamaya gelir. Bu yüzden mağazanın verisini `app/uninstalled` geldiğinde silmeyin: 30 gün içindeki bir yeniden kurulum olayı iptal eder ve veriyi yerinde bulmayı bekler. İşleyici erişim jetonunu kullanamaz (kaldırma onu iptal etti) ve yinelenmesi zararsız olmalıdır. Gövdesi `{store_domain, store_id}` biçimindedir; `store_id` belirleyicidir.

Bu 30 gün içinde `customers/redact` kaldırılmış uygulamaya da gelir.

## shop/update

`shop/update` izin istemez ve abone olan her kurulu uygulamaya gider. Mağazanın planı, adı, iletişim bilgileri, dili, para birimi veya logosu değiştiğinde ve mağazanın ana alan adı değiştiğinde gönderilir. Gövdesi `GET /api/v1/shop` çıktısıdır, `store_id` ile; alan adı değişiminde yeni adres `primary_url` alanındadır.

Alıcıların izleyeceği bağlantıları (ürün akışı adresi, e-postalardaki bağlantılar) `primary_url` ile kurun ve bu webhook geldiğinde güncelleyin.

## customers/marketing_consent_update

Pazarlama uygulamaları içindir: `read_marketing_audience` veya `write_marketing_consent` izniyle ve müşteri verisi düzeyi 2 ile alınır. Bir müşterinin e-posta veya SMS pazarlama izni nereden olursa olsun (ödeme sayfası, müşteri hesabı, abonelikten çık bağlantısı, bülten formu, yönetim paneli, CSV içe aktarma, bir uygulama, İYS) verildiğinde veya geri alındığında, izinli bir müşteri verilerinin silinmesini istediğinde gönderilir. Değişiklikle aynı işlemde kuyruğa girer; geri alınan bir değişiklik bildirim üretmez.

```json
{ "store_id": 1, "customer_id": 42, "channel": "email", "state": "unsubscribed", "consent_updated_at": "2026-11-12T08:30:00Z", "source": "unsubscribe" }
```

`channel` `email` veya `sms`dir; her kanalın izni ayrıdır ve ayrı bildirilir. `state` `subscribed` veya `unsubscribed`dır; silme talebinde `unsubscribed` ve `source` `erasure_request`, satıcının izinli bir müşteriyi silmesinde `unsubscribed` ve `source` `customer_deleted` gelir. `unsubscribed` gelen müşteriyi hemen gönderim listenizden çıkarın.

## customers/create, customers/update, customers/delete

`read_customers` ve en az 1. müşteri verisi düzeyiyle alınır; 0. düzeydeki bir yapılandırma bu konuları istediğinde reddedilir. Bir işlemde bir müşteri için tek bildirim gelir: aynı işlemde oluşturulup değiştirilen müşteri için yalnızca `customers/create`. `customers/create` ve `customers/update` gövdesi `GET /api/v1/customers/{id}` çıktısıdır ve uygulamanın düzeyine göre süzülür: 1. düzeyde `id`, `tags`, `accepts_marketing`, `orders_count`, `total_spent_cents` ve zamanlar gelir, iletişim alanları `null` olur. `customers/delete` gövdesinde yalnızca `id` bulunur; KVKK silme talebiyle silinen müşteriler için de gelir.

## sms/send

Yalnızca mağazanın SMS sağlayıcısı olarak seçtiği uygulamaya gider (`sms_provider = true` ve `write_sms`); abone olmak tek başına yetmez. Her SMS için bir istek gelir; yeniden denemeler olağan webhook'lar gibidir, yani aynı SMS iki kez gelebilir: `id` ile tekilleştirin.

```json
{ "id": 1000000000042, "to": "+905xxxxxxxxx", "body": "…", "encoding": "gsm7", "segments": 1, "notification": "order_confirmation", "order_id": 1000000001001, "store_id": 1000000000001 }
```

`encoding` `gsm7` veya `ucs2`, `segments` platformun saydığı parça sayısıdır. `notification` platformun bildirimidir (`order_confirmation`, `shipping_confirmation` gibi); bir uygulamanın `POST /api/v1/sms` ile istediği SMS'te boştur. Sonucu `POST /api/v1/sms/{id}/status` ile bildirin ([Uygulama API'si](api.md#kaynaklar)).

## iys/consent

Yalnızca mağazanın seçtiği SMS sağlayıcı uygulamaya ve uygulamanın sürümü `sms_commercial = true` ise gider; uygulama bu konuya yalnızca o zaman abone olabilir. Platform her 10 dakikada bir, mağazanın kaydettiği pazarlama izinlerini ve retlerini en çok 100 olaylık gruplarla gönderir; uygulama onları satıcının markasıyla İYS'ye işler.

```json
{ "store_id": 1000000000001, "events": [ { "id": 7, "channel": "email", "recipient": "ayse@example.com", "state": "granted", "consent_at": "2026-11-12T08:30:00Z", "source": "HS_WEB" } ] }
```

`state` `granted` veya `withdrawn`dır; `source` İYS'nin kaynak kodudur (`HS_WEB`, `HS_FIZIKSEL_ORTAM`, `HS_EORTAM`). `channel` `email` veya `sms`dir; `recipient` e-postada adres, SMS'te iznin verildiği cep telefonu numarasıdır (E.164, `+905…`). Öteki konuların tersine platform yanıtı okur:

```json
{ "results": [ { "id": 7, "status": "recorded" } ] }
```

`status` `recorded` (işlendi), `rejected` (İYS reddetti; `error` nedenini söyler) veya `retry` (bir sonraki turda yeniden gönderilir) olur. İYS'de yapılan retleri uygulama `POST /api/v1/customers/{id}/marketing_consent` ile `"source": "iys"` olarak mağazaya yazar.
