Skip to main content

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, so expect a delivery within a few minutes of the on-chain event.

Event Types

Protocol-level events (swaps, staking, liquidations) are not yet supported.

Supported Chains

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

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:
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.

Headers

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.
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.