Alerts & Webhooks

Get notified when watched addresses send or receive funds — by email or straight to your systems via webhook.

Address watchlists monitor on-chain activity for you. When a watched address is involved in a matching transaction, OpenScan.AI sends a notification by email and/or to a webhook URL you control.

How it works

1. Sign in at xdcscan.io.
2. Add an address to your watchlist from any address page (Watch button) or via the Account API.
3. Choose which events trigger notifications: incoming/outgoing native transfers, ERC-20, ERC-721, and ERC-1155 transfers.
4. Pick delivery channels: email, webhook, or both.

Notifications fire when the transaction is indexed — typically within seconds of block confirmation.

Managing watchlist entries via API

curl -X POST https://xdcscan.io/account/api/v1/user/watchlist \
  -H "Authorization: Bearer $OPENSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address_hash": "0x1234567890abcdef1234567890abcdef12345678",
    "name": "Treasury wallet",
    "notification_settings": {
      "native": { "incoming": true, "outgoing": true },
      "ERC-20": { "incoming": true, "outgoing": false }
    },
    "notification_methods": { "email": true, "webhook": true }
  }'

Webhook setup

Configure your webhook endpoint URL in Account → Notifications. The endpoint must:

• Accept POST requests with a JSON body.
• Respond with a 2xx status within 10 seconds (failed deliveries are retried with backoff).
• Be reachable over HTTPS.

Webhook payload

{
  "event": "watchlist.transaction",
  "watchlist_entry": {
    "address_hash": "0x1234567890abcdef1234567890abcdef12345678",
    "name": "Treasury wallet"
  },
  "transaction": {
    "hash": "0x9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b",
    "from": "0x0000000000000000000000000000000000000001",
    "to": "0x1234567890abcdef1234567890abcdef12345678",
    "value": "1500000000000000000000",
    "block": 89000123,
    "timestamp": "2026-08-30T12:34:56Z"
  }
}

Verifying deliveries

Each delivery includes an X-OpenScan-Signature header — an HMAC-SHA256 of the raw body keyed with the secret shown when you create the webhook. Verify it before processing:

import crypto from "node:crypto";

function isValid(rawBody, signature, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Building on alerts

Webhooks turn the explorer into an event source. Common patterns:

• Treasury monitoring — alert on any outgoing transfer above a threshold.
• Bridge relayers — trigger downstream actions when deposits land.
• Compliance feeds — stream watched-address activity into your SIEM.

For high-volume or custom filtering needs, poll the REST API directly — see the whale alert example in SDK Examples.

Limits

• Watchlist size and webhook rate limits scale with your account tier; the free tier comfortably covers personal monitoring.
• Notifications are at-least-once: your endpoint should deduplicate on transaction.hash.