Implementing Webhooks

What are Webhooks?

Webhooks allow Aelix to push real-time event notifications to your application rather than requiring you to poll for updates. They are ideal for event-driven architectures and reduce unnecessary API calls.

Step 1 — Register Your Endpoint

In the Developer Portal, go to Dashboard → Webhooks → Add Endpoint. Enter your HTTPS URL and select the event types you want to receive:

• account.created — New account opened
• payment.completed — Payment successfully processed
• payment.failed — Payment declined or failed
• transaction.posted — Transaction recorded on account
• kyc.status_changed — KYC verification update

Step 2 — Verify Signatures

Every webhook delivery includes an X-Aelix-Signature header containing an HMAC-SHA256 hash of the request body, signed with your webhook secret. Always verify this before processing:

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody, 'utf8')
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(expected, 'hex'),
Buffer.from(signature, 'hex')
);
}

Step 3 — Respond Quickly

Your endpoint must respond with HTTP 200 within 5 seconds. If processing takes longer, acknowledge immediately and process asynchronously:

app.post('/webhooks/aelix', (req, res) => {
// Acknowledge immediately
res.status(200).json({ received: true });
// Process asynchronously
processQueue.add(req.body);
});

Step 4 — Handle Retries

If your endpoint returns a non-200 response or times out, Aelix retries with exponential back-off:

Step 5 — Test Locally with Ngrok

During development, use ngrok to expose your local server:

ngrok http 3000
# Outputs: https://abc123.ngrok.io

# Register https://abc123.ngrok.io/webhooks/aelix in the portal