Webhook Integration Tutorial

Introduction to Webhooks

Webhooks allow your application to receive real-time updates from the Fractio API. Instead of constantly polling our API for changes, webhooks push data to your application as soon as an event occurs.

Setting Up Webhooks

Step 1: Create a Webhook Endpoint

First, you need to create an endpoint on your server that will receive webhook events. This endpoint should be able to handle POST requests.

// Example endpoint using Express.js
app.post('/webhook', (req, res) => {
    const event = req.body;
    // Process the event
    console.log('Received webhook event:', event);
    res.sendStatus(200);
});
        

Step 2: Register Your Webhook

Use the Fractio API to register your webhook endpoint:

curl -X POST "https://api.fractio.com/v1/webhooks" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://your-app.com/webhook",
       "events": ["property.updated", "investment.created"]
     }'
        

Step 3: Verify Webhook Signatures

To ensure the webhook requests are coming from Fractio, verify the signature:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
    const hmac = crypto.createHmac('sha256', secret);
    const digest = hmac.update(payload).digest('hex');
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest));
}

app.post('/webhook', (req, res) => {
    const signature = req.headers['x-fractio-signature'];
    const isValid = verifyWebhookSignature(JSON.stringify(req.body), signature, 'your_webhook_secret');
    
    if (isValid) {
        // Process the webhook
        console.log('Verified webhook:', req.body);
        res.sendStatus(200);
    } else {
        res.status(403).send('Invalid signature');
    }
});
        

Handling Webhook Events

Different events will have different payloads. Here's an example of how to handle a 'property.updated' event:

app.post('/webhook', (req, res) => {
    const event = req.body;
    
    switch(event.type) {
        case 'property.updated':
            handlePropertyUpdate(event.data);
            break;
        case 'investment.created':
            handleNewInvestment(event.data);
            break;
        // Handle other event types
        default:
            console.log('Unhandled event type:', event.type);
    }
    
    res.sendStatus(200);
});

function handlePropertyUpdate(data) {
    console.log('Property updated:', data.property_id);
    // Update your local database or trigger other actions
}

function handleNewInvestment(data) {
    console.log('New investment:', data.investment_id);
    // Process the new investment
}
        

Testing Webhooks

Use the Fractio API Playground to simulate webhook events and test your implementation:

1. Go to the API Playground
2. Navigate to the Webhooks section
3. Select an event type and customize the payload
4. Click "Send Test Event" to your registered webhook URL

Best Practices

• Respond quickly to webhook requests (within 5 seconds) to avoid timeouts
• Implement proper error handling and logging
• Use a queueing system for processing webhook events asynchronously
• Monitor your webhook endpoint's performance and availability

Conclusion

Webhooks are a powerful way to keep your application in sync with Fractio's data in real-time. By following this tutorial, you've learned how to set up, secure, and handle webhook events from the Fractio API.