geliştirici belgeleri

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:

İ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

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.

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).

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.