Webhook Examples

Real-world webhook implementation examples and patterns.

Subscribe to Webhooks

First, create a webhook subscription using the API:

curl -X POST https://api.snsauctions.xyz/api/v1/webhooks/create \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/sns-auctions",
    "events": ["auction.bid", "auction.settled", "auction.created"]
  }'

Example Receiver (Node/Express)

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

// Verify webhook authenticity
function verifyWebhookSignature(payload, signature) {
  const computedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');
  return computedSignature === signature;
}

app.post('/webhooks/sns-auctions', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const eventId = req.headers['x-webhook-id'];
  const eventType = req.headers['x-webhook-event'];
  const timestamp = req.headers['x-webhook-timestamp'];
  
  const payload = req.body;

  // Verify signature
  if (!verifyWebhookSignature(payload, signature)) {
    console.warn('Invalid webhook signature');
    return res.status(401).json({ error: 'Signature verification failed' });
  }

  // Process event
  console.log(`Received ${eventType} event (ID: ${eventId})`);

  switch (eventType) {
    case 'auction.bid':
      console.log(`New bid on ${payload.domain}:`, payload.data);
      // Your logic here
      break;
      
    case 'auction.settled':
      console.log(`Auction settled: ${payload.auctionId}`);
      // Your logic here
      break;
      
    case 'auction.created':
      console.log(`New auction: ${payload.domain}`);
      // Your logic here
      break;

    case 'auction.bid.extended':
      console.log(`Snipe protection triggered on ${payload.domain}`);
      // Your logic here
      break;

    default:
      console.log(`Ignoring unknown event: ${eventType}`);
  }

  // Return 200 to acknowledge receipt (important!)
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook receiver listening on port 3000');
});

Example Receiver (Python/Flask)

from flask import Flask, request
import hmac
import hashlib
import json

app = Flask(__name__)
WEBHOOK_SECRET = os.environ['WEBHOOK_SECRET']

def verify_signature(payload, signature):
    computed = hmac.new(
        WEBHOOK_SECRET.encode(),
        json.dumps(payload).encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(computed, signature)

@app.route('/webhooks/sns-auctions', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    event_type = request.headers.get('X-Webhook-Event')
    event_id = request.headers.get('X-Webhook-ID')
    
    payload = request.get_json()

    if not verify_signature(payload, signature):
        print('Invalid webhook signature')
        return {'error': 'Signature verification failed'}, 401

    print(f'Received {event_type} event (ID: {event_id})')

    if event_type == 'auction.bid':
        domain = payload.get('domain')
        bidder = payload.get('data', {}).get('bidder')
        amount = payload.get('data', {}).get('bidAmount')
        print(f'New bid on {domain}: {amount} SOL from {bidder}')
        
    elif event_type == 'auction.settled':
        auction_id = payload.get('auctionId')
        print(f'Auction settled: {auction_id}')
        
    elif event_type == 'auction.created':
        domain = payload.get('domain')
        print(f'New auction: {domain}')

    # Acknowledge receipt
    return {'received': True}, 200

if __name__ == '__main__':
    app.run(port=3000)

Event Payload Format

Example webhook payload structure:

POST /webhooks/sns-auctions HTTP/1.1
Host: your-server.com
X-Webhook-Signature: <hmac-sha256 signature>
X-Webhook-ID: evt_abc123def456
X-Webhook-Event: auction.bid
X-Webhook-Timestamp: 1234567890
Content-Type: application/json

{
  "event": "auction.bid",
  "auctionId": "auction_123",
  "domain": "example.sol",
  "data": {
    "bidder": "7B4X5wUohEzB8UZjfAvaxS1huNY6q5p5XqvCH7r6T1Hj",
    "bidAmount": 2.5,
    "isNewTopBidder": true
  },
  "timestamp": 1234567890,
  "id": "evt_abc123def456"
}

Best Practices

  • Always verify the webhook signature before processing events
  • Return 200 OK quickly to acknowledge receipt (don't do heavy processing in the handler)
  • Store webhook events in a queue for async processing
  • Implement idempotency checks using the webhook event ID
  • Log all webhook events for debugging and audit trails
  • Set up monitoring for failed webhook deliveries
  • Use webhook secret rotation for enhanced security

Webhook Retry Logic

If your endpoint returns a non-2xx status code or times out, the system will automatically retry with exponential backoff. Always return 200 OK to prevent retries.

© 2026 SNSAuctions.xyz. Built on Solana.