Webhooks & Callbacks

Coming Soon

Webhooks are on our roadmap for Q2 2026. This page documents the planned functionality.

Want early access? Contact support@web3identity.com

Planned Features

Event Types

Event	Description	Status
ens.transfer	ENS name transferred	Planned
ens.expiring	Name expires within 30 days	Planned
ens.expired	Name has expired	Planned
ens.record_changed	Text record updated	Planned
wallet.transfer	ETH/token transfer	Planned
wallet.nft_transfer	NFT transferred	Planned
farcaster.follow	New Farcaster follow	Planned
farcaster.cast	New cast from user	Planned
price.alert	Token price threshold	Planned

---

Proposed API

Create Webhook

POST /api/webhooks
Content-Type: application/json

{
  "url": "https://your-app.com/webhook",
  "events": ["ens.transfer", "ens.expiring"],
  "filters": {
    "names": ["yourname.eth", "*.yourname.eth"]
  },
  "secret": "your-webhook-secret"
}

Response

{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhook",
  "events": ["ens.transfer", "ens.expiring"],
  "status": "active",
  "createdAt": "2026-02-08T12:00:00Z"
}

---

Webhook Payload Format

{
  "id": "evt_xyz789",
  "type": "ens.transfer",
  "timestamp": "2026-02-08T12:34:56Z",
  "data": {
    "name": "yourname.eth",
    "from": "0xabc...",
    "to": "0xdef...",
    "txHash": "0x123..."
  }
}

Signature Verification

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  
  if (!verifyWebhook(JSON.stringify(req.body), signature, SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook
  const { type, data } = req.body;
  console.log(`Received ${type}:`, data);
  
  res.status(200).send('OK');
});

---

Pricing (Proposed)

Plan	Webhooks	Events/Month	Price
Free	1	1,000	$0
Pro	10	50,000	$29/mo
Enterprise	Unlimited	Unlimited	Contact us

---

Alternative: Polling

Until webhooks launch, use polling:

// Check ENS ownership every hour
async function checkENSOwnership(name) {
  const response = await fetch(
    `https://api.web3identity.com/api/ens/${name}`
  );
  const data = await response.json();
  
  // Compare with cached value
  if (data.registrant !== cachedRegistrant) {
    console.log(`${name} transferred!`);
    // Handle the change
  }
  
  cachedRegistrant = data.registrant;
}

setInterval(() => checkENSOwnership('yourname.eth'), 3600000);

Efficient Batch Polling

// Poll multiple names efficiently
async function batchCheck(names) {
  const response = await fetch(
    `https://api.web3identity.com/api/ens/batch?names=${names.join(',')}`
  );
  return response.json();
}

---

Request This Feature

Help us prioritize by telling us your use case:

• Email: support@web3identity.com
• Twitter: @ATV_eth
• Subject: "Webhook Interest: [Your Use Case]"

Include:

1. Events you need
2. Expected volume
3. Your application type

---

Related

• ENS Resolution — Current ENS endpoints
• Rate Limits — Polling considerations
• x402 Payments — How billing will work