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.