Docs/API/Webhooks
Integration

Webhooks

Receive real-time notifications about events in your WardX-managed servers.

What are Webhooks?

Webhooks allow you to receive HTTP POST requests when specific events occur in your server. This enables integration with external services, custom bots, or your own applications.

Available Webhook Events

NFT Transfer Events

Triggered when NFTs from tracked collections are transferred. Useful for sales bots and holder tracking.

Event: nft.transfer

Verification Events

Triggered when members verify or lose verification status.

Events: verification.completed, verification.revoked

Giveaway Events

Triggered when giveaways end and winners are selected.

Events: giveaway.ended, giveaway.winner_selected

Webhook Payload

All webhook payloads follow a consistent JSON structure:

{
  "event": "nft.transfer",
  "timestamp": "2026-01-22T12:00:00Z",
  "serverId": "123456789012345678",
  "data": {
    "contractAddress": "0x...",
    "tokenId": "1234",
    "from": "0x...",
    "to": "0x...",
    "chain": "ethereum",
    "transactionHash": "0x..."
  }
}

Setting Up Webhooks

1

Create an Endpoint

Set up an HTTPS endpoint on your server that can receive POST requests. The endpoint must return a 2xx status code within 10 seconds.

2

Configure in Dashboard

Navigate to your server settings and add your webhook URL:

  • Enter your HTTPS endpoint URL
  • Select which events to subscribe to
  • Save your webhook secret for verification
3

Verify Signatures

All webhooks include a signature header for verification:

X-WardX-Signature: sha256=...

Verify the signature by computing HMAC-SHA256 of the request body using your webhook secret.

Signature Verification Example

// Node.js example
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

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

// Usage
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-wardx-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  console.log('Event:', req.body.event);
  res.status(200).send('OK');
});

Retry Policy

If your endpoint fails to respond with a 2xx status code, we'll retry with exponential backoff:

  • • Attempt 1: Immediate
  • • Attempt 2: After 1 minute
  • • Attempt 3: After 5 minutes
  • • Attempt 4: After 30 minutes
  • • Attempt 5: After 2 hours (final attempt)

Security Best Practices

  • • Always verify webhook signatures before processing
  • • Use HTTPS endpoints only
  • • Keep your webhook secret secure and rotate it periodically
  • • Respond quickly (within 10 seconds) to avoid timeouts
QuestsSupported Chains