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');
    }
});

Note: Always use HTTPS for your webhook endpoint to ensure secure communication.

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
}

Tip: Implement proper error handling and retry logic in your webhook handler to ensure you don't miss any events.

Testing Webhooks

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

Go to the API Playground
Navigate to the Webhooks section
Select an event type and customize the payload
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.