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ı.
Abonelik
Abonelikler biticaret.app.toml dosyasındadır ve kurulumda kaydedilir; her kod takası kurulumun aboneliklerini sürümdekilerle değiştirir.
[[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
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 birv1taşı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ğersatı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.
Teslim ve yeniden deneme
- 5 saniye içinde gelen bir
2xxteslim sayılır (store/redactiçin 25,iys/consentiç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
2xxsayacı sıfırlar. - Uygulama kaldırıldıktan sonra bekleyen teslimler başarısız sayılır;
app/uninstalledyine gönderilir.
Teslim kaydı ve yeniden gönderim
Uygulama kendi teslim kaydını okur ve bir teslimi yeniden gönderir:
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:
[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.
{ "store_id": 1, "customer_id": 42, "channel": "email", "state": "unsubscribed", "consent_updated_at": "2026-11-12T08:30:00Z", "source": "unsubscribe" }
channel email veya smsdir; her kanalın izni ayrıdır ve ayrı bildirilir. state subscribed veya unsubscribeddı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.
{ "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).
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.
{ "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 withdrawndır; source İYS'nin kaynak kodudur (HS_WEB, HS_FIZIKSEL_ORTAM, HS_EORTAM). channel email veya smsdir; 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:
{ "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.