Webhooks Integration Guide
Comprehensive guide to integrating XRPL.Sale webhooks for real-time event notifications, including setup, payload examples, and best practices.
12 min read
Integration Guide
Real-time Events
What are Webhooks?
Webhooks are HTTP callbacks that XRPL.Sale sends to your application when specific events occur. Instead of repeatedly polling our API, webhooks enable real-time notifications for investments, project updates, and system events.
Real-time
Instant notifications when events occur
Efficient
No need to poll APIs continuously
Reliable
Built-in retry logic and delivery guarantees
Supported Webhook Events
Investment Events
investment.created
New investment received
investment.confirmed
Investment confirmed on XRPL
investment.tokens_distributed
Tokens sent to investor
investment.refunded
Investment refunded
investment.failed
Investment processing failed
Project Events
project.launched
Project goes live
project.tier_completed
Tier fully funded
project.milestone_reached
Funding milestone achieved
project.sale_ended
Sale period concluded
project.cancelled
Project cancelled
System Events
system.maintenance_start
Scheduled maintenance begins
system.maintenance_end
Maintenance completed
system.network_status
XRPL network status updates
Setting Up Webhooks
Step 1: Create Webhook Endpoint
Create an HTTP endpoint in your application that can receive POST requests from XRPL.Sale.
Node.js/Express Example
const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.json());
app.post('/webhooks/xrpl-sale', (req, res) => {
const signature = req.headers['x-xrpl-sale-signature'];
const payload = JSON.stringify(req.body);
// Verify webhook signature
if (!verifySignature(payload, signature)) {
return res.status(401).send('Invalid signature');
}
// Process the event
handleWebhookEvent(req.body);
res.status(200).send('OK');
});
function verifySignature(payload, signature) {
const expectedSignature = crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature, 'hex'),
Buffer.from(expectedSignature, 'hex')
);
}Python/Flask Example
from flask import Flask, request, jsonify
import hashlib
import hmac
import os
app = Flask(__name__)
@app.route('/webhooks/xrpl-sale', methods=['POST'])
def handle_webhook():
signature = request.headers.get('X-XRPL-Sale-Signature')
payload = request.get_data()
# Verify signature
if not verify_signature(payload, signature):
return jsonify({'error': 'Invalid signature'}), 401
# Process event
event_data = request.get_json()
handle_webhook_event(event_data)
return jsonify({'status': 'success'}), 200
def verify_signature(payload, signature):
expected_signature = hmac.new(
os.environ['WEBHOOK_SECRET'].encode('utf-8'),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected_signature)Step 2: Register Your Webhook
Register your webhook endpoint with XRPL.Sale using our API or dashboard.
API Registration
curl -X POST https://api.xrpl.sale/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-domain.com/webhooks/xrpl-sale",
"events": [
"investment.created",
"investment.confirmed",
"project.launched",
"project.tier_completed"
],
"active": true,
"description": "Main webhook endpoint for investments"
}'Step 3: Handle Webhook Events
Implement event handlers for different webhook event types.
function handleWebhookEvent(eventData) {
const { event_type, data, timestamp, event_id } = eventData;
// Log the event
console.log(`Received webhook: ${event_type} (ID: ${event_id})`);
switch (event_type) {
case 'investment.created':
handleNewInvestment(data);
break;
case 'investment.confirmed':
handleInvestmentConfirmed(data);
break;
case 'project.launched':
handleProjectLaunched(data);
break;
case 'project.tier_completed':
handleTierCompleted(data);
break;
default:
console.log(`Unhandled event type: ${event_type}`);
}
}
function handleNewInvestment(data) {
// Update your database
// Send confirmation email
// Update analytics
console.log(`New investment: ${data.amount} XRP for project ${data.project_id}`);
}
function handleInvestmentConfirmed(data) {
// Update investment status
// Trigger token distribution if applicable
// Send success notification
console.log(`Investment confirmed: ${data.investment_id}`);
}Webhook Payload Examples
investment.created
{
"event_type": "investment.created",
"event_id": "evt_1a2b3c4d5e6f",
"timestamp": "2025-01-15T10:30:00Z",
"api_version": "2025-01",
"data": {
"investment_id": "inv_abc123",
"project_id": "proj_xyz789",
"investor_account": "rN7n7otEwF2whQQDhUn6S4Mv8Hx4tMkL8a",
"amount_xrp": "1000.000000",
"tier_info": {
"tier": 3,
"price_per_token": "0.002",
"tokens_expected": "500000"
},
"transaction": {
"hash": "E3FE6EA3D48F0C2B639448020EA4F03D4F4F8FFEDFCEECCDCFD7EB4F7D8E5D4A",
"ledger_index": 75432100,
"destination_tag": 12345
},
"status": "pending_confirmation",
"created_at": "2025-01-15T10:30:00Z"
}
}investment.confirmed
{
"event_type": "investment.confirmed",
"event_id": "evt_2b3c4d5e6f7g",
"timestamp": "2025-01-15T10:35:00Z",
"api_version": "2025-01",
"data": {
"investment_id": "inv_abc123",
"project_id": "proj_xyz789",
"investor_account": "rN7n7otEwF2whQQDhUn6S4Mv8Hx4tMkL8a",
"confirmed_amount_xrp": "1000.000000",
"final_tier_allocation": [
{
"tier": 2,
"amount_xrp": "500.000000",
"tokens": "333333.333333"
},
{
"tier": 3,
"amount_xrp": "500.000000",
"tokens": "250000.000000"
}
],
"total_tokens": "583333.333333",
"transaction": {
"hash": "E3FE6EA3D48F0C2B639448020EA4F03D4F4F8FFEDFCEECCDCFD7EB4F7D8E5D4A",
"ledger_index": 75432100,
"confirmed_at": "2025-01-15T10:35:00Z"
},
"status": "confirmed",
"tokens_to_distribute": "583333.333333"
}
}project.tier_completed
{
"event_type": "project.tier_completed",
"event_id": "evt_3c4d5e6f7g8h",
"timestamp": "2025-01-15T14:20:00Z",
"api_version": "2025-01",
"data": {
"project_id": "proj_xyz789",
"project_name": "Innovative DeFi Protocol",
"tier_completed": 2,
"tier_details": {
"tier": 2,
"price_per_token": "0.0015",
"total_tokens": "10000000",
"total_value_xrp": "15000.000000"
},
"completion_stats": {
"total_investors": 127,
"completion_time": "2025-01-15T14:20:00Z",
"time_to_complete_hours": 72.5
},
"next_tier": {
"tier": 3,
"price_per_token": "0.002",
"total_tokens": "10000000",
"starts_at": "2025-01-15T14:20:00Z"
},
"project_progress": {
"tiers_completed": 2,
"total_tiers": 5,
"total_raised_xrp": "25000.000000",
"progress_percentage": 40
}
}
}Security & Verification
Webhook Signature Verification
Every webhook includes a signature header to verify authenticity. Always verify signatures to ensure webhooks come from XRPL.Sale.
Signature Headers
X-XRPL-Sale-Signature: HMAC-SHA256 signature of the request body
X-XRPL-Sale-Timestamp: Unix timestamp when the webhook was sent
X-XRPL-Sale-Event-ID: Unique identifier for the webhook event
Security Best Practices
Verify Signatures
Always validate webhook signatures
Use HTTPS
Only accept webhooks over encrypted connections
Validate Timestamps
Reject old webhook deliveries
Idempotency
Handle duplicate webhook deliveries
Rate Limiting
Implement proper rate limiting
Error Handling
Gracefully handle processing errors
Retry Logic & Reliability
Retry Schedule
If your webhook endpoint returns an error or times out, XRPL.Sale will retry delivery with exponential backoff.
Retry Attempts:
- • 1st retry: 5 seconds
- • 2nd retry: 25 seconds
- • 3rd retry: 2 minutes
- • 4th retry: 10 minutes
- • 5th retry: 1 hour
- • Final attempt: 6 hours
Response Requirements
Success Response
HTTP 200-299 status code
Response Time
Must respond within 30 seconds
Retry Trigger
4xx/5xx status codes or timeout
Testing & Debugging
Sending Test Events
Use our API to send test webhook events to verify your integration.
curl -X POST https://api.xrpl.sale/webhooks/test \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"webhook_id": "wh_abc123",
"event_type": "investment.created",
"test_data": {
"amount_xrp": "100.000000",
"investor_account": "rTestAccount123..."
}
}'Webhook Delivery Logs
Monitor webhook delivery status and debug issues through our dashboard or API.
curl -X GET "https://api.xrpl.sale/webhooks/wh_abc123/deliveries" \
-H "Authorization: Bearer YOUR_API_KEY"
# Response includes:
{
"deliveries": [
{
"id": "del_xyz789",
"event_id": "evt_1a2b3c",
"status": "success",
"response_code": 200,
"delivered_at": "2025-01-15T10:35:00Z",
"duration_ms": 150
}
]
}Webhook Management
List & Update Webhooks
List Webhooks
GET /api/webhooks
Update Webhook
PATCH /api/webhooks/{id}
Delete Webhook
DELETE /api/webhooks/{id}
Dashboard Management
Manage webhooks through our web dashboard with visual monitoring and debugging tools.
Delivery success rates
Response time metrics
Error rate monitoring
Event type statistics