Custody Webhook'u Alma

Bir custody sağlayıcısının, platformun kendisine gönderdiği bir işlemin ilerlemesini bildirmek için çağırdığı gelen endpoint. Bu sayfa yalnızca platformun bağlı olduğu custody servisini işletiyorsanız gereklidir; partner entegrasyonları bu endpoint'i çağırmaz.

OAuth access token ile değil, sağlayıcıya özel webhook gizli anahtarı ile doğrulanır (admin panelinin custody ayarlarında üretilir ve bir kez gösterilir). Webhook'u client sertifikası gerektirecek şekilde yapılandırılmış bir sağlayıcı, kendisine verilen sertifikayı TLS el sıkışmasında da sunmalıdır (bkz. mTLS Client Sertifikaları; subject sağlayıcı anahtarıdır).

İstek

POST /v2/webhooks/custodial

POST /v2/webhooks, aynı davranışa sahip kullanımdan kalkmış bir takma addır; yalnızca hâlâ bu adresle yapılandırılmış gönderenler için tutulur. Yeni bir göndereni bununla yapılandırmayın.

Başlıklar

Ad	Açıklama
Authorization	Zorunlu (ya da X-Webhook-Token). Sağlayıcının doğrulama şemasına göre: Basic <base64(username:webhook_secret)> ya da Bearer <webhook_secret>
X-Webhook-Token	Authorization başlığını ayarlayamayan gönderenler için Authorization: Bearer alternatifi. Webhook gizli anahtarını taşır
X-Apex-Delivery-Id	Önerilir. Gönderenin bu teslimat için kimliği. Platform teslimatı bu kimlikle kaydeder; aynı teslimat iki kez gelirse tek kayıt olur
Content-Type	Zorunlu. application/json

Gövde

Alan	Tip	Zorunlu	Açıklama
id	string	Evet	Custody işlem kimliği: platformun işlemi gönderdiği kimlik
custody_transaction_id	string	Hayır	Custody servisinin kendi kayıt kimliği. Yalnızca kaydedilir
external_id	string	Hayır	İsteğe bağlı harici referans
type	string	Evet	Custody işlem türü, örneğin execute_contract
status	string	Evet	pending_approval, queued, signing, broadcast, confirmed, rejected, failed, cancelled ya da expired
transaction_hash	string	Hayır	Yayınlandıktan sonra zincir üzerindeki işlem hash'i
contract_address	string	Hayır	İşlemin oluşturduğu ya da çağırdığı kontrat
gas_used	number	Hayır	Makbuz oluştuktan sonra kullanılan gas
effective_gas_price_wei	string	Hayır	Ondalık string. Yalnızca kaydedilir
gas_fee_wei	string	Hayır	Ondalık string. Yalnızca kaydedilir
gas_fee_native	string	Hayır	Ondalık string. Yalnızca kaydedilir
error	string | null	Hayır	rejected / failed / cancelled / expired için hata nedeni
created_at	string	Evet	ISO 8601
updated_at	string	Evet	ISO 8601

Bilinmeyen alanlar yok sayılır.

Örnek

curl --request POST \
  --url '{{baseUrl}}/v2/webhooks/custodial' \
  --header 'Authorization: Bearer <webhook_secret>' \
  --header 'X-Apex-Delivery-Id: 3b1f6c1e-8c55-4d47-9a0e-4b1c2f0c9a11' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "6913872755654191dede37da",
    "type": "execute_contract",
    "status": "confirmed",
    "transaction_hash": "0xc34e006659d532a0c8212a8ec624a08cfab3ffbd102936a681ab81e3cf7e0c6d",
    "contract_address": "0x39247A80f1c0ddcEfb4986fA7A59E919E1F2Fa38",
    "gas_used": 142037,
    "error": null,
    "created_at": "2026-02-06T13:04:58.802Z",
    "updated_at": "2026-02-06T13:05:09.911Z"
  }'

Yanıt

Teslimat kabul edildiğinde gövdesiz 200.

Bir teslimat nasıl işlenir

• Nihai durumlar geri okunur. confirmed, rejected, failed, cancelled ve expired için platform gövdeye güvenmez: işlemi custody servisinden okur ve custody'nin yanıtını (durum, hash, kontrat adresi, gas, hata) yayınlar. Webhook gizli anahtarı teslimatı kimin gönderdiğini kanıtlar, ne olduğunu değil.
• Bu okuma başarısız olursa ya da kayıt bulunamazsa teslimat 503 (kod 20009) ile reddedilir ve gönderen tekrar dener. Platformun kendi sorgulaması işlemi yine sonuçlandırır; yani karar gecikir ama kaybolmaz.
• Ara durumlar (pending_approval, queued, signing, broadcast) geldiği gibi iletilir.
• Platformda zaten done ya da error durumuna ulaşmış bir işlem ilk kararını korur; sonradan gelen bir teslimat onu değiştirmez.

Hatalar

Durum	Kod	Açıklama
400	-1	Gövde ayrıştırılamıyor ya da bir alanın tipi hatalı
401	-1	Kimlik bilgileri hiçbir sağlayıcının webhook gizli anahtarıyla eşleşmiyor ya da sağlayıcı sertifika gerektiriyor ve el sıkışmada ona verilen sertifika sunulmadı
503	20009	Nihai durum custody servisinden geri okunamadı. Teslimatı tekrar deneyin

Hata biçimi için Hatalar sayfasına bakın.