Monitoring Webhooks

Overview

Monitoring webhooks push signed HTTPS notifications to your endpoint when on-chain activity happens on addresses you watch. Configure them in the developer console: choose an endpoint URL, the event types you care about, the chains to watch, and up to 25 addresses per webhook. Watched addresses are polled roughly every 5 minutes, and an event is reported once it is a few blocks deep (about 2–3 minutes on Ethereum and Base) so that a chain reorganisation can never retract a delivery. Expect a delivery within roughly 5–10 minutes of the on-chain event. Compound V2 lending events are the exception: they come from an hourly index of the whole protocol, so allow up to about an hour.

Event Types

Lending events

Decoded from the lending protocols’ own events: Aave V2 and V3, Compound V3 and Morpho Blue on Ethereum and Base, and Compound V2 on Ethereum. These are the same events the credit score’s Borrowing History reads.

Event	Fires when
`liquidation`	A watched address’s position is liquidated (Aave `LiquidationCall`, Compound V3 absorb, Compound V2 `LiquidateBorrow`, Morpho Blue `Liquidate`)
`borrow`	A watched address takes on new debt
`repay`	Debt on a watched address’s position is repaid, by the address or a third party (liquidation repayments are reported as `liquidation`, never as `repay`)
`supply`	A watched address supplies an asset (Aave, Compound V3 and Morpho Blue, including collateral)
`withdraw`	A watched address withdraws a supplied asset (Aave, Compound V3 and Morpho Blue, including collateral)

Lending events are available on Ethereum and Base only; a webhook that subscribes to one must include at least one of those chains. Watching an address starts from the moment monitoring first sees it: its earlier borrowing history is never replayed as events.

Wallet activity events

Available on every supported chain.

Event	Fires when
`transfer`	An ERC20 token moves to or from a watched address
`mint`	A token is minted to a watched address (transfer from the zero address)
`burn`	A token is burned from a watched address (transfer to the zero address)
`transaction`	Native currency (ETH, POL, BNB, …) moves to or from a watched address
`approval`	A watched address grants an ERC20 allowance to a spender

Score events

Event	Fires when
`score_change`	A watched address’s credit score is recomputed and differs from the last recorded score

A score is recomputed when anyone requests it, when the cache warmer refreshes a popular address, and, for addresses watched by a score_change webhook, automatically within about 10 minutes of new on-chain activity on any of the webhook’s chains. Only complete (non-provisional) scores are compared, and only a change in the score value fires the event. Each recorded score is also available from the score history endpoint. Score events are not tied to a chain: blockchain and transaction_hash are null in the payload, and the webhook’s chains only say where activity triggers a recomputation. Other protocol events (swaps, staking) are not yet supported.

Supported Chains

Ethereum, Base, Optimism, Arbitrum, Polygon, BNB Chain, Avalanche, Linea, Celo, and Robinhood Chain. Chain values in payloads use lowercase slugs (ethereum, base, bsc, robinhood, …).

Endpoint Requirements

HTTPS only, on port 443 or 8443, resolving to a public IP address (private and internal hosts are rejected, both at registration and at delivery time).
Respond with any 2xx status within 10 seconds. Anything else counts as a failed delivery.
At most 10 webhooks per user and 25 addresses per webhook.

Delivery Payload

Every delivery is a POST with a JSON body:

{
  "event_type": "transfer",
  "blockchain": "base",
  "address": "0xab5801a7d398351b8be11c439e05c5b3259aec9b",
  "transaction_hash": "0x9f1a...",
  "timestamp": "2026-08-20T17:04:11.482919+00:00",
  "data": {
    "from": "0x1234...",
    "to": "0xab58...",
    "direction": "in",
    "contract_address": "0x8335...",
    "token_symbol": "USDC",
    "token_decimal": "6",
    "value": "25000000",
    "block_number": 34118260
  }
}

The data object varies by event type: transaction events carry value_wei, approval events carry spender and the raw allowance value, and token events carry the fields shown above. Lending events carry the protocol, the market contract and the amounts, as raw integers in the asset’s smallest unit (strings, to keep full precision). For a liquidation, asset and amount_raw are the debt repaid and collateral_asset / collateral_amount_raw the collateral seized (for Compound V2, the seized cToken and an amount in cTokens). counterparty is the caller, recipient, repayer or liquidator, depending on the event.

{
  "event_type": "liquidation",
  "blockchain": "ethereum",
  "address": "0xab5801a7d398351b8be11c439e05c5b3259aec9b",
  "transaction_hash": "0x4c2e...",
  "timestamp": "2026-10-31T21:10:04.118204+00:00",
  "data": {
    "protocol": "aave_v3",
    "market_address": "0x87870bca3f3fd6335c3f4ce8392d69350b4fa4e2",
    "asset": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "amount_raw": "2500000000",
    "counterparty": "0x2222...",
    "collateral_asset": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "collateral_amount_raw": "400000000000000000",
    "block_number": 23701254,
    "block_time": "2026-10-31T21:03:11+00:00",
    "log_index": 212
  }
}

A score_change event carries the previous and current scores and the difference between them:

{
  "event_type": "score_change",
  "blockchain": null,
  "address": "0xab5801a7d398351b8be11c439e05c5b3259aec9b",
  "transaction_hash": null,
  "timestamp": "2026-11-02T08:15:40.102331+00:00",
  "data": {
    "previous": {
      "timestamp": "2026-10-30T09:12:44+00:00",
      "score": 741,
      "decile": 8,
      "range": "good",
      "model_version": "andromeda_1.4"
    },
    "current": {
      "timestamp": "2026-11-02T08:15:39+00:00",
      "score": 702,
      "decile": 7,
      "range": "fair",
      "model_version": "andromeda_1.4"
    },
    "delta": -39,
    "range_changed": true
  }
}

Headers

Header	Meaning
`X-Webhook-Signature`	`t=<unix_timestamp>,v1=<hex_hmac>` — see verification below
`X-Event-Type`	The event type, e.g. `transfer`
`X-Webhook-Id`	The webhook’s ID
`X-Webhook-Delivery-Id`	Unique per delivery — use it for idempotency (retries reuse the ID)
`X-Webhook-Timestamp`	Same unix timestamp as `t` in the signature header

Verifying Signatures

Each webhook has a signing secret, shown once when you create it. The signature is HMAC-SHA256 over the string {t}.{raw_body}, where t is the timestamp from the signature header and raw_body is the exact request body bytes. Always verify the signature and reject stale timestamps (5 minutes is a reasonable tolerance) to prevent replays.

import hashlib
import hmac
import time

def verify_webhook(secret: str, signature_header: str, raw_body: bytes,
                   tolerance_seconds: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    timestamp, signature = int(parts["t"]), parts["v1"]

    if abs(time.time() - timestamp) > tolerance_seconds:
        return False  # stale — possible replay

    expected = hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

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

function verifyWebhook(
  secret: string,
  signatureHeader: string,
  rawBody: string,
  toleranceSeconds = 300,
): boolean {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("=", 2) as [string, string]),
  );
  const timestamp = Number(parts.t);
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Compute the HMAC over the raw request body bytes, not a re-serialized copy of the parsed JSON — serialization differences will break verification.

Retries and Failure Handling

Failed deliveries are retried up to 4 times with increasing backoff: 1 minute, 5 minutes, 30 minutes, then 2 hours.
Every attempt is recorded in the delivery history, visible in the console next to each webhook.
After 10 consecutive failed attempts (across deliveries), the webhook is automatically disabled. Re-enable it from the console once your endpoint is healthy — the failure counter resets on the first successful delivery.

Testing

Use the test button in the console to send a synthetic test event through the real delivery pipeline. Test deliveries appear in the delivery history but are never retried and don’t count toward auto-disable.

When a new address is added to a webhook, monitoring starts from the current chain head — historical activity is not backfilled.

Get Started

Use Cases

Guides

On-Chain Reputation

Compliance

Overview

Event Types

Lending events

Wallet activity events

Score events

Supported Chains

Endpoint Requirements

Delivery Payload

Headers

Verifying Signatures

Retries and Failure Handling

Testing

​Overview

​Event Types

​Lending events

​Wallet activity events

​Score events

​Supported Chains

​Endpoint Requirements

​Delivery Payload

​Headers

​Verifying Signatures

​Retries and Failure Handling

​Testing

Overview

Event Types

Lending events

Wallet activity events

Score events

Supported Chains

Endpoint Requirements

Delivery Payload

Headers

Verifying Signatures

Retries and Failure Handling

Testing