Blockchain Webhook Kurulumu: İmzalar, Tekilleştirme ve Yeniden Oynatma

Bir EVM cüzdan adresini izleyin ve cüzdan etkinliği bildirimleri veya akıllı sözleşme olay izlemesi için yerel transferlerini, token transferlerini ve eşleşen sözleşme loglarını HTTPS uç noktanızda alın. Geliştiriciler ve AI Agent'lar aynı HTTP abonelik API'sini kullanır. ERC-20 USDT / USDC ödeme bildirimleri için stablecoin ödeme alıcısını takip edin.

• İlk adım: Aşağıdaki doğrulama örneğini kullanarak ham gövde imzalarını doğrulayan bir alıcı dağıtın.
• Tamamlanma kriteri: applied_version >= change_version olduktan sonra, eşleşen zincir üstü etkinlik alıcınıza ulaşır, imza doğrulamasını geçer ve olay id değerine göre kalıcı olarak kaydedilir; bir abonelik oluşturulması test mesajı göndermez.

Webhook erişim seçenekleri.

Bu rehberin tamamlamanıza yardımcı olduğu görevler

• Kimliği doğrulanmış bir abonelik oluşturarak, izlenen adresleri ekleyerek ve gelen olayları doğrulayarak cüzdan adresi etkinliğini alın.
• İzlenen adresler için log olaylarını inceleyerek ve alıcınızda address, topics ve data alanlarını filtreleyerek eşleşen sözleşme loglarını izleyin.
• Abonelik ilerlemesini kontrol ederek ve saklanan eşleşmeleri yeniden oynatarak (replay) kesintiye uğrayan teslimatı kurtarın, ardından yeniden oynatma penceresinin dışındaki boşlukları geriye dönük doldurun.

Bir abonelik; tek bir HTTPS alıcı URL'sini, bir imzalama gizli anahtarını (secret), izlenen EVM adreslerini ve zorunlu bir chains nesnesini birleştirir. Adresler o nesnedeki her zincir için geçerlidir. API'yi bir x-api-key başlığıyla kullanın; hesabınızdaki herhangi bir aktif anahtar, tüm aboneliklerini yönetebilir. Başlamadan önce bir API anahtarı edinin. Push OpenAPI her işlemi ve webhook şemasını listeler.

Cüzdan adresi etkinliğini bağlama

1. Orijinal istek gövdesini doğrulayan, olayları id değerine göre kalıcı olarak kaydeden ve bunları 10 saniye içinde onaylayan bir alıcı dağıtın.
2. GET /v1/push/chains yanıtını okuyun, ardından HTTPS URL'niz ve seçilen zincirlerle bir abonelik oluşturun. Döndürülen id ve secret değerlerini kaydedin.
3. Cüzdan adreslerini ekleyin. applied_version >= change_version olmasını bekleyin ve her zincirin applied_from_block değerini kaydedin; eşleşme oradan başlar.
4. Transferleri ve logları işleyin ve boşlukları veya değiştirilen blokları kurtarın. Bildirimleri ödeme işlemede kullanmadan önce token sözleşmelerini, alıcıları ve tam sayı tutarlarını filtreleyin.

Webhook, WebSocket veya yoklama arasında seçim yapma

• Webhook, izlenen adres olaylarını teslimat yeniden denemeleri ve saklanan eşleşmelerin yeniden oynatılmasıyla (replay) bir HTTPS alıcısına gönderir.
• WebSocket, kalıcı bir bağlantı üzerinden newHeads ve filtrelenmiş logs akışı sağlar. Bağlantı koptuktan sonra yeniden bağlanın, yeniden abone olun ve kaçırılan blokları sorgulayın.
• Yoklama, kendi imlecinizle sınırlı blok aralıklarında eth_getLogs sorgular; bunu ödemeleri izlemek veya eksik logları geriye dönük doldurmak için kullanın.

WebSocket desteği için GET /v1/chains içindeki ws ve subscriptions alanlarını kontrol edin. ws değeri false ise, o zincir kimliği doğrulanmış GET /v1/push/chains listesinde göründüğünde adres Webhook'ları yine de bir seçenektir. Tek başına RPC desteği Push desteğini sağlamaz.

Adres kapasitesi

Self servis, abonelik başına 1,000,000 adrese kadar destekler ve kayıtta kullanılabilir. Bir abonelik, tek bir alıcı URL ile birden fazla zinciri kapsar. Kurumsal kapasite, abonelik başına 10,000,000 / 100,000,000 adresi destekler; etkinleştirmek için bize ulaşın. Geliştiriciler ve AI Agent'lar aynı kapasite seçeneklerine ve fiyatlara sahiptir. Her iki katman da fiyatlandırmada gösterilen aynı adres-gün ve teslim edilen olay oranlarını kullanır.

Bir abonelik oluşturma

Mevcut zincirler ve bunların minimum, varsayılan ve maksimum onay sayıları için GET /v1/push/chains yanıtını okuyun. Bir blok, head - block + 1 >= confirmations olduğunda serbest bırakılır. Her zincir {} sağlayarak kendi varsayılanını kullanabilir. En az bir zincir gereklidir; yeni zincirler mevcut aboneliklere otomatik olarak katılmaz.

URL'yi alıcınızla değiştirerek ve zincir listesinden zincirleri seçerek aşağıdaki örneği create.json olarak kaydedin. URL, 443 numaralı bağlantı noktasında HTTPS kullanmalı, IP sabiti yerine bir ana makine adı içermeli ve kullanıcı bilgisi veya parça (fragment) içermemelidir.

{
  "url": "https://hooks.example.com/push",
  "chains": {
    "bsc_mainnet": {
      "confirmations": 1
    },
    "base_mainnet": {}
  }
}

Ortamınızda BLOCKVECTRA_API_KEY değerini ayarlayın, ardından çalıştırın:

PUSH_URL='https://api.blockvectra.com/v1/push'
curl --fail-with-body -sS "$PUSH_URL/chains" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"
curl --fail-with-body -sS "$PUSH_URL/subscriptions" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d @create.json > subscription.json

Başarılı bir oluşturma, HTTP 201 ve adresi olmayan bir online abonelik döndürür. Sayısal id ve secret değerlerini güvenli bir şekilde saklayın. Gizli anahtar yalnızca oluşturma sırasında veya POST /subscriptions/{subscription_id}/rotate-secret ile döndürülür; rotasyon, örtüşme olmaksızın tüm zincirlerde anında yürürlüğe girer. Test mesajı gönderilmez.

Adres ekleme ve listeleme

Örnek adresleri izlediğiniz adreslerle değiştirerek bir adres grubunu addresses.json olarak kaydedin:

{
  "addresses": [
    "0x9725db73f2cd8657f3e1841e5689f210ee54a92d",
    "0x99d47bB552ae095159C251836De6A5d524076872"
  ]
}

SUBSCRIPTION_ID değerini döndürülen abonelik kimliğine ayarlayın:

curl --fail-with-body -sS "$PUSH_URL/subscriptions/$SUBSCRIPTION_ID/addresses/add" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -H 'Content-Type: application/json' -d @addresses.json
curl --fail-with-body -sS "$PUSH_URL/subscriptions/$SUBSCRIPTION_ID/addresses" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"
curl --fail-with-body -sS "$PUSH_URL/subscriptions/$SUBSCRIPTION_ID" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

Her ekleme çağrısı en fazla 10,000 adresi kabul eder. Girdi adresleri küçük harfli veya geçerli EIP-55 karışık harflidir; geçersiz girdi tüm grubu reddeder. Yinelenen adresler unchanged olarak sayılır, bu nedenle aynı ekleme isteğini yeniden göndermek güvenlidir. Adres listeleri limit ve page_token kullanır; next_page_token: null son sayfayı işaretler.

Adres eklemek change_version döndürür. applied_version >= change_version olana kadar GET /subscriptions/{subscription_id} yoklayın veya inceleyin; değişikliklerin uygulanması normalde yaklaşık 1 saniye sürer. Her zincirin applied_from_block değeri, zincir üstü işlemlerin ve logların eşleştirildiği geçerli bloğu tanımlar. Yeni adresler geriye dönük olarak eşleştirilmez.

Bir abonelik oluşturmak, abonelik kaynağının oluşturulduğunu onaylamak için HTTP 201 döndürür; HTTP 201, alıcınızın herhangi bir webhook iletimi aldığı anlamına gelmez. Platform, oluşturma veya adres kaydı sırasında doğrulama ya da test mesajları göndermez. Alıcınızda teslimatı doğrulamak için izlenen adreslerde ve zincirlerde eşleşen zincir üstü etkinliğin gerçekleşmesini beklemelisiniz.

Olay biçimi

Her POST; type: push.events, created_at ve data içerir. data; subscription_id, bir chain, complete_through_block ve events içerir. İlerlemeyi zincir başına kaydedin: bir blok birden fazla mesaja yayılabilir, bu nedenle bireysel olay blok numaraları bir tamamlanma işareti değildir. Her mesaj en fazla 1,000 olay, 1 MiB ve 50 blok içerir.

{
  "type": "push.events",
  "created_at": "2026-10-02T03:00:05Z",
  "data": {
    "subscription_id": 48213,
    "chain": "bsc_mainnet",
    "complete_through_block": 64000121,
    "events": [
      {
        "id": "evt_payvsqb6ogymhmehrs2wl5xcky",
        "type": "native.transfer",
        "ref": "eip155:56:0x7b19944dc683c33e8dedba259cb6939f7271f70f2eeb6ca5e456cccb57cc1eff:tx",
        "from": "0xe0a2100d7dad33f70c4bb765323cb96b2400c844",
        "to": "0x9725db73f2cd8657f3e1841e5689f210ee54a92d",
        "amount": "150000000000000000",
        "block_number": 64000120,
        "block_hash": "0x327892a3e5699a43981f0fbcc5e490628641d92c040eb0429fb550ba3a73c3bf",
        "block_timestamp": "2026-10-02T03:00:00Z",
        "tx_hash": "0x7b19944dc683c33e8dedba259cb6939f7271f70f2eeb6ca5e456cccb57cc1eff",
        "tx_index": 3,
        "matched": [
          {
            "address": "0x9725db73f2cd8657f3e1841e5689f210ee54a92d",
            "role": "to"
          }
        ]
      },
      {
        "id": "evt_lgcdattb6l2k3ejuhe4mtdljkm",
        "type": "token.transfer",
        "ref": "eip155:56:0x3be3448e6f54ebfa928d5997a0cb2d5e9d3186c5ebfa293ad45b7edc72483a76:7",
        "standard": "erc20",
        "token": "0x55d398326f99059ff775485246999027b3197955",
        "from": "0x0f94e5283c41c29a8f4dff8c17f68bdfb59f07df",
        "to": "0x99d47bb552ae095159c251836de6a5d524076872",
        "token_id": null,
        "amount": "25000000000000000000",
        "batch_index": null,
        "block_number": 64000121,
        "block_hash": "0x6a8146159162f182c091d17eac7d03e95dc92ce80de704c958ca2528306aff15",
        "block_timestamp": "2026-10-02T03:00:00Z",
        "tx_hash": "0x3be3448e6f54ebfa928d5997a0cb2d5e9d3186c5ebfa293ad45b7edc72483a76",
        "tx_index": 5,
        "log_index": 7,
        "matched": [
          {
            "address": "0x99d47bb552ae095159c251836de6a5d524076872",
            "role": "to"
          }
        ]
      },
      {
        "id": "evt_sgliw3ficdf6gaa6zzx4ew6vni",
        "type": "log",
        "ref": "eip155:56:0x3be3448e6f54ebfa928d5997a0cb2d5e9d3186c5ebfa293ad45b7edc72483a76:8",
        "address": "0xb54ffbe723264b84cf74947127a6914cf87fc593",
        "topics": [
          "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
          "0x00000000000000000000000099d47bb552ae095159c251836de6a5d524076872",
          "0x000000000000000000000000b54ffbe723264b84cf74947127a6914cf87fc593"
        ],
        "data": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "block_number": 64000121,
        "block_hash": "0x6a8146159162f182c091d17eac7d03e95dc92ce80de704c958ca2528306aff15",
        "block_timestamp": "2026-10-02T03:00:00Z",
        "tx_hash": "0x3be3448e6f54ebfa928d5997a0cb2d5e9d3186c5ebfa293ad45b7edc72483a76",
        "tx_index": 5,
        "log_index": 8,
        "matched": [
          {
            "address": "0x99d47bb552ae095159c251836de6a5d524076872",
            "role": "topic1"
          }
        ]
      }
    ]
  }
}

Bir abonelik içinde, olay id değerine göre tekilleştirin; abonelikler arasında ref ve type kullanın. Bilinmeyen alanları ve olay türlerini yoksayın. Finansal işlem yapmadan önce zincir üstü gerçekleri doğrulayın.

İmzaları doğrulama

Başlıklar webhook-id, webhook-timestamp, webhook-signature ve bv-subscription-id şeklindedir. Gizli anahtarı yalnızca oluşturduğunuz aboneliklerden seçin; bilinmeyen kimlikleri reddedin. JSON ayrıştırmadan önce, orijinal istek gövdesinin baytlarını kullanarak webhook-id.webhook-timestamp.raw-body üzerinde HMAC-SHA256 doğrulayın. İmza v1,<base64> biçimindedir; yaklaşık beş dakikalık zaman damgası kaymasına izin verin ve sabit zamanda (constant time) karşılaştırın.

Bu Node.js fonksiyonu ham gövdeyi bir Buffer olarak, istek başlıklarını ve depolanan gizli anahtarlarla abonelik kimliklerinin bir haritasını kabul eder:

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyPush(rawBody, headers, secrets) {
  const subscriptionId = headers['bv-subscription-id'];
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signature = headers['webhook-signature'];
  if ([subscriptionId, id, timestamp, signature].some(v => typeof v !== 'string')) return false;
  const secret = secrets.get(subscriptionId);
  if (typeof secret !== 'string' || !secret.startsWith('whsec_')) return false;
  if (!/^\d{10}$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const match = /^v1,([A-Za-z0-9+/]{43}=)$/.exec(signature);
  if (!match) return false;
  const received = Buffer.from(match[1], 'base64');
  const expected = createHmac('sha256', Buffer.from(secret.slice(6), 'base64'))
    .update(`${id}.${timestamp}.`).update(rawBody).digest();
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Doğrulamadan sonra gövdeyi ayrıştırın, işlemeyi kalıcı kılın ve 10 saniye içinde 2xx döndürün. Abonelik kimliği başlığı, imza doğrulanana kadar güvenilmezdir.

İlk etkinliğinizi doğrulama

Aboneliği online tutun. Adres değişikliği uygulandıktan sonra eşleşen zincir üstü etkinliği bekleyin ve alıcınızın olayı doğruladığını ve kalıcı olarak depoladığını kontrol edin.

Doğrulamadan sonra dinlemeyi durdurma

Adresleri izlemeyi durdurmak için kaldırılacak adresleri addresses.json içine kaydedin ve POST /subscriptions/{subscription_id}/addresses/remove çağrısı yapın:

curl --fail-with-body -sS "$PUSH_URL/subscriptions/$SUBSCRIPTION_ID/addresses/remove" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -H 'Content-Type: application/json' -d @addresses.json

Her kaldırma çağrısı en fazla 10,000 adresi kabul eder. Şu anda izlenmeyen bir adres unchanged olarak sayılır. Çağrı change_version döndürür. applied_version >= change_version olduğunda, bu geçerli bloktan sonraki bloklar artık kaldırılan adreslerle eşleşmez. Önceden eşleşen olaylar (yoldaki, yeniden denenen veya kuyruktaki) yine de teslim edilir; önceden teslim edilmiş olaylar geri çekilmez.

Yapılandırmayı veya adresleri silmeden dinlemeyi geçici olarak duraklatmak için status değerini offline olarak ayarlayın:

curl --fail-with-body -sS -X PATCH "$PUSH_URL/subscriptions/$SUBSCRIPTION_ID" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status":"offline"}'

Bir offline abonelik dinlemeyi ve teslimatı durdurur, eşleştirme indeksinden adresleri kaldırır ve çevrimdışı kaldığı herhangi bir tam UTC günü için hiçbir adres ücreti almaz. Tüm yapılandırma (URL, gizli anahtar, adresler, zincirler ve onaylar) korunur. {"status":"online"} yaması uygulamak, geçerli etkin bloktan itibaren dinlemeyi sürdürür ve çevrimdışı dönemi geriye dönük doldurmaz.

url, key_id, status veya chains değiştirmek için PATCH /subscriptions/{subscription_id} üzerinde JSON Merge Patch kullanın: bir zincir nesnesi onu ekler veya günceller, null ise kaldırır. En az bir zincir kalmalıdır. Aboneliği kalıcı olarak silmek için:

curl --fail-with-body -sS -X DELETE "$PUSH_URL/subscriptions/$SUBSCRIPTION_ID" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

DELETE işlemi aboneliği kalıcı olarak kaldırır, tüm zincirlerde teslimatı derhal durdurur ve gizli anahtarı ile adresleri yok eder.

Teslimat, yeniden denemeler ve yeniden oynatma

Teslimat en az bir kez yapılır. Her aboneliğin zinciri blok ve blok içindeki konuma göre sıralanır; başarısız gruplar o zincirdeki sonraki olayları engeller. Farklı zincirler bağımsız ilerlemeye sahiptir ve eşzamanlı olarak POST edebilir. Aynı grubun yeniden denenmesi webhook-id değerini korur, ancak değiştirilen bir grup yeni bir ID'ye sahip olabilir: grupları değil, olayları tekilleştirin.

10 saniye içindeki herhangi bir 2xx yanıtı dayanıklı işlemeyi onaylar. Yönlendirmeler izlenmez; 3xx ve 410 başarısızlıktır. Bir arızadan sonra yeniden denemeler anında, 5 saniye, 30 saniye, 2 dakika, 10 dakika, 30 dakika ve 1 saatlik aralıklarla, ardından saatlik olarak devam eder. Bir 429 Retry-After yanıtı bekleme süresini bir saate kadar uzatabilir. Teslimat durduğunda her zincirin condition, last_error ve next_attempt_at alanlarını inceleyin. Koşullar receiver_failing, insufficient_balance ve key_revoked şeklindedir; sonuncusu key_id değerinin başka bir etkin hesap anahtarına yamalanmasını gerektirir.

Teslim edilmeyen olayların süresi saklama penceresinin dışında dolar ve subscription.gap üretir. POST /subscriptions/{subscription_id}/replay, chain ve from_block parametrelerini alır; GET /push/chains içindeki replayable_from_block ve aboneliğin ilerleme durumuna danışın. Yeniden oynatma (replay) mevcut eşleşmeleri teslim eder ve bir adres veya zincir eklenmeden önceki olayları kurtaramaz.

chain.reorg, önceden teslim edilmiş blokların değiştirildiğini size bildirir; bu bir teslimat boşluğu olduğunu göstermez. Onay sayınızdan daha sığ yeniden düzenlemeler görünmezdir. 1,024 blok derinliğe kadar teslim edilmiş blokları etkileyen yeniden düzenlemeler için kanonik olaylar yeni idlerle otomatik olarak yeniden iletilir. Değiştirilen olayları ref ile işaretleyin veya atın, kanonik olayları saklayın ve id ile tekilleştirin; ödeme kayıtları için ref ve tx_hash ile mutabakat sağlayın. Daha derin bir yeniden düzenleme zinciri durdurur: GET /push/chains içinde halted durumunu kontrol edin; zincir geri yüklendikten sonra kanonik yeniden teslimat gerçekleşir. Kontrol olayı complete_through_block değerini ilerletmez.

İsteğe bağlı olarak from_block, to_block, limit ve page_token ekleyerek GET /subscriptions/{subscription_id}/events?chain=... ile teslim edilen veri olaylarını sorgulayın. Geçmiş satırları event, replay_epoch, orphaned ve delivered_at içerir; orphaned: true daha sonra değiştirilen bir bloğu işaretler. Geçmiş erişimi 402 insufficient_balance (data.reason: balance_exhausted veya free_grant_exhausted), 403 key_cap_exhausted (data.cu_cap) veya 429 rate_limited (key_rate_limit veya free_plan_call_limit) döndürebilir. Bir 429 cost_exceeds_burst, request_exceeds_burst nedenine ve data.max değerine sahiptir: yeniden denemeden önce anlık kapasiteyi (burst capacity) artırın. Geçersiz aralıklar ve yeniden deneme yönergeleri için hata yönetimine bakın.

Faturalandırma ve örnek

Ağırlıklar GET /v1/plans üzerinden gelir. Teslim edilen veri olayları, başarılı geçmiş istekleri ve adres-günler ayrı ağırlıklara sahiptir; geçmiş dışındaki yönetim çağrıları, kontrol olayları, başarısız teslimatlar ve otomatik yeniden denemeler ücretsizdir. Teslim edilen her olay bir kez ücretlendirilir; müşteri tarafından yapılan yeniden oynatma ve kanonik olay yeniden teslimatı yeni teslimat ücretlerine tabi olur.

Adres faturalandırması, abonelikler arasında paylaşılan hesap ücretsiz adres hakkından sonra (önce daha eski abonelikler olmak üzere), her aboneliğin UTC gününün çevrimiçi bölümündeki en büyük adres sayısını kullanır. İki abonelikteki aynı adres iki kez sayılır; zincir eklemek adres ücretlerini değil, olay ücretlerini değiştirir. Tüm UTC günü boyunca çevrimdışı olan bir aboneliğin adres ücreti yoktur.

CU ölçümü ve dönüştürme için faturalandırma kurallarına ve fiyatlandırma sayfasına bakın.

İlgili kaynaklar

• Desteklenen olayları, zincir kapsamını ve fiyatlandırmayı Blockchain Webhook API'sine genel bakış sayfasında karşılaştırın.