Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nzochain.com/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks give you a push-based integration with NZOChain’s threat detection system. Instead of polling the API repeatedly to check whether a wallet’s risk level has changed, you register an HTTPS endpoint and NZOChain delivers a POST request to it the moment a threat event occurs. This is the fastest way to react to new threats — your application receives alerts in real time, with no polling overhead.

​
Subscribe to events

Send a POST request to the subscribe endpoint to register your webhook URL and choose which events you want to receive.

​
Endpoint

POST https://api.nzochain.com/v1/api/webhooks/subscribe

​
Request body

​
url
string
required
Your HTTPS endpoint that will receive webhook event payloads. Must be a publicly accessible URL with a valid TLS certificate.
​
events
string[]
required
The event types to subscribe to. See the event types table below for available values.
​
wallet
string
Scope this subscription to a single wallet address. When omitted, you receive events for all wallets NZOChain is monitoring on your account.

​
Example request

{
  "url": "https://your-app.com/webhooks/nzochain",
  "events": ["threat.detected", "approval.infinite", "status.critical"],
  "wallet": "0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234"
}

​
Event types

EventTrigger
risk.score.changedRiskScore increased or decreased significantly
threat.detectedNew malicious contract or approval detected
approval.infiniteInfinite token approval detected
phishing.attemptPhishing domain or fake dApp detected
status.criticalWallet status escalated to CRITICAL

​
Webhook payload

NZOChain sends a JSON POST request to your endpoint when an event fires. The payload includes the event type, the affected wallet, a timestamp, and a data object with event-specific details.

​
Example payload — threat.detected

{
  "event": "threat.detected",
  "wallet": "0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "threatType": "MALICIOUS_CONTRACT",
    "severity": "HIGH",
    "message": "Interaction with known malicious contract detected",
    "contractAddress": "0xAbC..."
  }
}

​
Example payload — risk.score.changed

{
  "event": "risk.score.changed",
  "wallet": "0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234",
  "timestamp": "2024-01-15T11:00:00Z",
  "data": {
    "previousScore": 23,
    "currentScore": 74,
    "previousStatus": "SAFE",
    "currentStatus": "HIGH RISK"
  }
}

​
Verifying webhook authenticity

Each webhook request includes an X-NZOChain-Signature header. You should verify this header before processing the payload to confirm the request genuinely came from NZOChain and has not been tampered with. The signature is an HMAC-SHA256 hash of the raw request body, signed with your webhook secret. You can find your webhook secret in the NZOChain dashboard under Settings → Webhooks. 
const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, webhookSecret) {
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expectedSignature)
  );
}

// Express example
app.post('/webhooks/nzochain', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-nzochain-signature'];

  if (!verifyWebhook(req.body, signature, process.env.NZOCHAIN_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  console.log('Verified event:', event.event);
  res.sendStatus(200);
});

​
Handling delivery and retries

When NZOChain sends a webhook event to your endpoint, your server must respond with an HTTP 200 OK status within 5 seconds to acknowledge receipt. If your endpoint does not respond in time, or responds with a non-2xx status, NZOChain will retry the delivery with exponential backoff.
Respond with 200 OK as quickly as possible — ideally before you process the event. If your processing logic is slow, acknowledge receipt immediately and handle the event asynchronously in a background queue. NZOChain marks a delivery as failed after 5 seconds and will retry, which can result in duplicate deliveries if your processing is slow.