Blockchain-Webhook-Setup: Signaturen, Deduplizierung und Replay

Überwachen Sie eine EVM-Wallet-Adresse und empfangen Sie deren native Transfers, Token-Transfers und passende Contract-Logs an Ihrem HTTPS-Endpunkt für Benachrichtigungen über Wallet-Aktivitäten oder die Überwachung von Smart-Contract-Ereignissen. Entwickler und KI-Agenten nutzen dieselbe HTTP-Abonnement-API. Für ERC-20-USDT- / USDC-Zahlungsbenachrichtigungen folgen Sie dem Leitfaden für Stablecoin-Zahlungsempfänger.

• Erster Schritt: Stellen Sie einen Empfänger bereit, der Raw-Body-Signaturen verifiziert, unter Verwendung des unten stehenden Verifizierungsbeispiels.
• Abgeschlossen, wenn: Nach applied_version >= change_version passende On-Chain-Aktivität Ihren Empfänger erreicht, die Signaturverifizierung besteht und anhand der Ereignis-id dauerhaft gespeichert wird; das Erstellen eines Abonnements sendet keine Testnachricht.

Webhook-Zugriffsoptionen.

Aufgaben, die dieser Leitfaden abdeckt

• Wallet-Adressaktivität empfangen durch Erstellen eines authentifizierten Abonnements, Hinzufügen überwachter Adressen und Verifizieren eingehender Ereignisse.
• Passende Contract-Logs überwachen durch Prüfen von log-Ereignissen für überwachte Adressen und Filtern von address, topics und data in Ihrem Empfänger.
• Unterbrochene Zustellungen wiederherstellen durch Prüfen des Abonnementfortschritts und Replay gespeicherter Treffer sowie anschließendes Nachfüllen von Lücken außerhalb des Replay-Fensters.

Ein Abonnement kombiniert eine HTTPS-Empfangs-URL, ein Signatur-Geheimnis, überwachte EVM-Adressen und ein erforderliches chains-Objekt. Adressen gelten für jede Chain in diesem Objekt. Verwenden Sie die API mit einem x-api-key-Header; jeder aktive Schlüssel in Ihrem Konto kann alle seine Abonnements verwalten. API-Schlüssel anfordern, bevor Sie beginnen. Das Push-OpenAPI-Dokument listet alle Operationen und Webhook-Schemas auf.

Wallet-Adressaktivität anbinden

1. Stellen Sie einen Empfänger bereit, der den ursprünglichen Request-Body verifiziert, Ereignisse nach id speichert und sie innerhalb von 10 Sekunden bestätigt.
2. Lesen Sie GET /v1/push/chains und erstellen Sie anschließend ein Abonnement mit Ihrer HTTPS-URL und den ausgewählten Chains. Speichern Sie die zurückgegebene id und das secret.
3. Fügen Sie die Wallet-Adressen hinzu. Warten Sie auf applied_version >= change_version und notieren Sie für jede Chain den Wert applied_from_block; der Abgleich beginnt dort.
4. Verarbeiten Sie Transfers und Logs und stellen Sie Lücken oder ersetzte Blöcke wieder her. Filtern Sie Token-Contracts, Empfänger und ganzzahlige Beträge, bevor Sie Benachrichtigungen in der Zahlungsverarbeitung verwenden.

Webhook, WebSocket oder Polling wählen

• Webhook sendet Ereignisse überwachter Adressen an einen HTTPS-Empfänger, mit Zustellwiederholungen und Replay gespeicherter Treffer.
• WebSocket streamt newHeads und gefilterte logs über eine dauerhafte Verbindung. Stellen Sie die Verbindung wieder her, abonnieren Sie erneut und fragen Sie verpasste Blöcke nach einem Verbindungsabbruch ab.
• Polling fragt eth_getLogs in begrenzten Blockbereichen mit Ihrem eigenen Cursor ab; verwenden Sie es, um Zahlungen zu überwachen oder fehlende Logs nachzufüllen.

Prüfen Sie ws und subscriptions in GET /v1/chains auf WebSocket-Unterstützung. Wenn ws false ist, sind Adress-Webhooks weiterhin eine Option, sofern diese Chain in der authentifizierten Liste von GET /v1/push/chains erscheint. RPC-Unterstützung allein begründet noch keine Push-Unterstützung.

Adresskapazität

Self-Service unterstützt bis zu 1.000.000 Adressen pro Abonnement und steht direkt nach der Registrierung zur Verfügung. Ein Abonnement deckt mehrere Chains mit einer einzigen Empfangs-URL ab. Die Enterprise-Kapazität unterstützt 10.000.000 / 100.000.000 Adressen pro Abonnement; kontaktieren Sie uns zur Aktivierung. Entwickler und KI-Agenten haben dieselben Kapazitätsoptionen und Preise. Beide Stufen nutzen dieselben Raten pro Adresstag und zugestelltem Ereignis, wie unter Preise dargestellt.

Ein Abonnement erstellen

Lesen Sie GET /v1/push/chains für verfügbare Chains und deren minimale, standardmäßige und maximale Bestätigungsanzahlen aus. Ein Block wird freigegeben, wenn head - block + 1 >= confirmations erfüllt ist. Jede Chain kann ihren Standardwert verwenden, indem {} übergeben wird. Mindestens eine Chain ist erforderlich; neue Chains treten bestehenden Abonnements nicht automatisch bei.

Speichern Sie das folgende Beispiel als create.json, ersetzen Sie die URL durch Ihren Empfänger und wählen Sie Chains aus der Chain-Liste aus. Die URL muss HTTPS auf Port 443 verwenden, einen Hostnamen anstelle eines IP-Literals enthalten und darf keine Benutzerinformationen oder Fragmente aufweisen.

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

Setzen Sie BLOCKVECTRA_API_KEY in Ihrer Umgebung und führen Sie anschließend Folgendes aus:

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

Ein erfolgreiches Erstellen gibt HTTP 201 und ein online-Abonnement ohne Adressen zurück. Speichern Sie dessen numerische id und das secret sicher. Das Secret wird nur bei der Erstellung oder bei POST /subscriptions/{subscription_id}/rotate-secret zurückgegeben; eine Rotation wird auf allen Chains sofort und ohne Überschneidung wirksam. Es wird keine Testnachricht gesendet.

Adressen hinzufügen und auflisten

Speichern Sie einen Adress-Batch als addresses.json und ersetzen Sie die Beispieladressen durch diejenigen, die Sie überwachen:

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

Setzen Sie SUBSCRIPTION_ID auf die zurückgegebene Abonnement-ID:

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"

Jeder Hinzufügen-Aufruf akzeptiert höchstens 10.000 Adressen. Eingegebene Adressen sind in Kleinbuchstaben oder gültiger EIP-55-Gemischtbuchstabenschreibweise; ungültige Eingaben weisen den gesamten Batch ab. Wiederholte Adressen zählen als unchanged, sodass das erneute Senden derselben Hinzufügen-Anfrage sicher ist. Adresslisten verwenden limit und page_token; next_page_token: null kennzeichnet die letzte Seite.

Das Hinzufügen von Adressen gibt change_version zurück. Pollen oder prüfen Sie GET /subscriptions/{subscription_id}, bis applied_version >= change_version gilt; Änderungen benötigen normalerweise etwa 1 Sekunde zur Anwendung. Der Wert applied_from_block jeder Chain gibt den wirksamen Block an, ab dem On-Chain-Transaktionen und Logs abgeglichen werden. Neue Adressen werden nicht rückwirkend abgeglichen.

Das Erstellen eines Abonnements gibt HTTP 201 zurück, um zu bestätigen, dass die Abonnement-Ressource erstellt wurde; HTTP 201 bedeutet nicht, dass Ihr Empfänger bereits einen Webhook-Push erhalten hat. Die Plattform sendet bei der Erstellung oder Adressregistrierung keine Verifizierungs- oder Testnachrichten. Sie müssen warten, bis passende On-Chain-Aktivität auf den überwachten Adressen und Chains auftritt, um die Zustellung an Ihrem Empfänger zu überprüfen.

Ereignisformat

Jeder POST enthält type: push.events, created_at und data. data enthält subscription_id, eine chain, complete_through_block und events. Erfassen Sie den Fortschritt pro Chain: Ein Block kann sich über mehrere Nachrichten erstrecken, sodass einzelne Blocknummern von Ereignissen keine Abschlussmarkierung darstellen. Jede Nachricht enthält höchstens 1.000 Ereignisse, 1 MiB und 50 Blöcke.

{
  "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"
          }
        ]
      }
    ]
  }
}

Deduplizieren Sie innerhalb eines Abonnements nach der Ereignis-id; über Abonnements hinweg verwenden Sie ref und type. Ignorieren Sie unbekannte Felder und Ereignistypen. Verifizieren Sie On-Chain-Fakten, bevor Sie finanzielle Aktionen durchführen.

Signaturen verifizieren

Die Header lauten webhook-id, webhook-timestamp, webhook-signature und bv-subscription-id. Wählen Sie das Secret nur aus Abonnements, die Sie erstellt haben; weisen Sie unbekannte IDs ab. Verifizieren Sie HMAC-SHA256 über webhook-id.webhook-timestamp.raw-body unter Verwendung der Bytes des ursprünglichen Request-Bodys, bevor Sie JSON parsen. Die Signatur lautet v1,<base64>; erlauben Sie eine Zeitstempelabweichung von etwa fünf Minuten und vergleichen Sie in konstanter Zeit.

Diese Node.js-Funktion akzeptiert den unveränderten Body als Buffer, Request-Header und eine Map von Abonnement-IDs zu gespeicherten Secrets:

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);
}

Nach der Verifizierung parsen Sie den Body, speichern das Verarbeitungsergebnis dauerhaft und geben innerhalb von 10 Sekunden einen 2xx-Statuscode zurück. Der Abonnement-ID-Header gilt als nicht vertrauenswürdig, bis die Signatur verifiziert ist.

Ihr erstes Ereignis verifizieren

Halten Sie das Abonnement online. Warten Sie nach der Anwendung der Adressänderung auf passende On-Chain-Aktivität und prüfen Sie, ob Ihr Empfänger das Ereignis verifiziert und dauerhaft speichert.

Empfang nach der Verifizierung beenden

Um die Überwachung von Adressen zu beenden, speichern Sie die zu entfernenden Adressen in addresses.json und rufen Sie POST /subscriptions/{subscription_id}/addresses/remove auf:

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

Jeder Entfernen-Aufruf akzeptiert höchstens 10.000 Adressen. Eine Adresse, die derzeit nicht überwacht wird, zählt als unchanged. Der Aufruf gibt change_version zurück. Sobald applied_version >= change_version gilt, stimmen Blöcke ab diesem wirksamen Block nicht mehr mit den entfernten Adressen überein. Zuvor abgeglichene Ereignisse (in Übertragung, in Wiederholung oder in der Warteschlange) werden weiterhin zugestellt; bereits zugestellte Ereignisse werden nicht zurückgezogen.

Um das Lauschen vorübergehend zu pausieren, ohne die Konfiguration oder Adressen zu löschen, setzen Sie status auf offline:

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"}'

Ein offline-Abonnement stoppt das Lauschen und die Zustellung, entlädt Adressen aus dem Abgleichsindex und verursacht für jeden vollen UTC-Tag, an dem es offline bleibt, keine Adressgebühr. Die gesamte Konfiguration (URL, Secret, Adressen, Chains und Bestätigungen) bleibt erhalten. Das Patchen von {"status":"online"} nimmt das Lauschen ab dem aktuellen wirksamen Block wieder auf und füllt die Offline-Phase nicht rückwirkend nach.

Verwenden Sie JSON Merge Patch auf PATCH /subscriptions/{subscription_id}, um url, key_id, status oder chains zu ändern: Ein Chain-Objekt fügt diese hinzu oder aktualisiert sie, und null entfernt sie. Mindestens eine Chain muss verbleiben. Um das Abonnement dauerhaft zu löschen:

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

DELETE entfernt das Abonnement dauerhaft, stoppt die Zustellung über alle Chains hinweg sofort und vernichtet das Secret sowie die Adressen.

Zustellung, Wiederholungen und Replay

Die Zustellung erfolgt mindestens einmal. Jede Chain eines Abonnements ist nach Block und Position im Block geordnet; fehlgeschlagene Batches blockieren nachfolgende Ereignisse auf dieser Chain. Unterschiedliche Chains haben einen unabhängigen Fortschritt und können gleichzeitig POST-Anfragen senden. Eine Wiederholung eines identischen Batches behält webhook-id bei, aber ein veränderter Batch kann eine neue ID erhalten: Deduplizieren Sie Ereignisse, nicht Batches.

Jeder 2xx-Statuscode innerhalb von 10 Sekunden bestätigt die dauerhafte Verarbeitung. Weiterleitungen wird nicht gefolgt; 3xx und 410 gelten als Fehlschläge. Nach einem Fehlschlag erfolgen Wiederholungen in Intervallen von sofort, 5 Sekunden, 30 Sekunden, 2 Minuten, 10 Minuten, 30 Minuten und 1 Stunde, danach stündlich. Ein Retry-After-Header bei 429 kann die Wartezeit auf bis zu eine Stunde verlängern. Prüfen Sie condition, last_error und next_attempt_at jeder Chain, wenn die Zustellung stoppt. Die Bedingungen lauten receiver_failing, insufficient_balance und key_revoked; Letzteres erfordert das Patchen von key_id auf einen anderen aktiven Kontoschlüssel.

Nicht zugestellte Ereignisse laufen außerhalb des Aufbewahrungsfensters ab und erzeugen subscription.gap. POST /subscriptions/{subscription_id}/replay akzeptiert chain und from_block; konsultieren Sie replayable_from_block in GET /push/chains und den Fortschritt des Abonnements. Replay stellt vorhandene Treffer zu und kann keine Ereignisse von vor dem Hinzufügen einer Adresse oder Chain wiederherstellen.

chain.reorg benachrichtigt Sie darüber, dass bereits zugestellte Blöcke ersetzt wurden; es weist nicht auf eine Zustellungslücke hin. Reorgs, die flacher als Ihre Bestätigungsanzahl sind, bleiben unsichtbar. Bei Reorgs, die zugestellte Blöcke bis zu einer Tiefe von 1.024 Blöcken betreffen, werden kanonische Ereignisse automatisch mit neuen ids erneut zugestellt. Markieren oder verwerfen Sie ersetzte Ereignisse anhand von ref, behalten Sie die kanonischen Ereignisse und deduplizieren Sie nach id; bei Zahlungsaufzeichnungen stimmen Sie anhand von ref und tx_hash ab. Ein tieferer Reorg hält die Chain an: Prüfen Sie halted in GET /push/chains; die kanonische Neuzustellung folgt, nachdem die Chain wiederhergestellt ist. Das Steuerereignis setzt complete_through_block nicht fort.

Fragen Sie zugestellte Datenereignisse mit GET /subscriptions/{subscription_id}/events?chain=... ab, optional unter Angabe von from_block, to_block, limit und page_token. Historienzeilen enthalten event, replay_epoch, orphaned und delivered_at; orphaned: true kennzeichnet einen später ersetzten Block. Der Zugriff auf den Verlauf kann 402 insufficient_balance (data.reason: balance_exhausted oder free_grant_exhausted), 403 key_cap_exhausted (data.cu_cap) oder 429 rate_limited (key_rate_limit oder free_plan_call_limit) zurückgeben. Ein 429 cost_exceeds_burst hat den Grund request_exceeds_burst und data.max: Erhöhen Sie die Burst-Kapazität vor einem erneuten Versuch. Siehe Fehlerbehandlung für ungültige Bereiche und Hinweise zu Wiederholungen.

Abrechnung und Beispiel

Gewichte stammen aus GET /v1/plans. Zugestellte Datenereignisse, erfolgreiche Historienanfragen und Adresstage haben separate Gewichte; Verwaltungsaufrufe außer Historie, Steuerereignisse, fehlgeschlagene Zustellungen und automatische Wiederholungen sind kostenlos. Jedes zugestellte Ereignis wird einmal berechnet; Replays durch Kunden und Neuzustellungen kanonischer Ereignisse verursachen neue Zustellgebühren.

Die Adressabrechnung verwendet die höchste Adressanzahl jedes Abonnements während seines Online-Zeitraums des UTC-Tages nach Abzug des über Abonnements hinweg geteilten kostenlosen Kontingents des Kontos (ältere Abonnements zuerst). Dieselbe Adresse in zwei Abonnements zählt doppelt; das Hinzufügen von Chains verändert die Ereignisgebühren, nicht die Adressgebühren. Ein Abonnement, das den gesamten UTC-Tag über offline ist, verursacht keine Adressgebühr.

Siehe Abrechnungsregeln und die Preisseite für CU-Messung und -Umrechnung.

Zugehörige Ressourcen

• Vergleichen Sie unterstützte Ereignisse, Chain-Abdeckung und Preise in der Übersicht zur Blockchain Webhook API.