Coming Soon: The Developers section is under active development. Documentation will be available soon.
Overview
Webhooks notify your application of events in real-time, eliminating the need for polling.
Setup
1. Create Webhook Endpoint
// Express example
app.post('/webhooks/centuari', express.raw({ type: 'application/json' }), (req, res) => {
const event = verifyAndParse(req);
handleEvent(event);
res.json({ received: true });
});
2. Register Webhook
curl -X POST https://api.centuari.io/v1/webhooks \
-H "Authorization: Bearer ck_live_..." \
-d '{
"url": "https://your-app.com/webhooks/centuari",
"events": ["position.matched", "position.matured"]
}'
Event Types
| Event | Description |
|---|
position.created | Order placed |
position.matched | Order matched |
position.matured | Position reached maturity |
position.liquidated | Position liquidated |
position.rolled | Auto-rollover executed |
withdrawal.completed | Withdrawal processed |
{
"id": "evt_abc123",
"type": "position.matched",
"timestamp": "2025-03-15T14:32:00Z",
"data": {
"positionId": "pos_xyz",
"userId": "user_123",
"rate": 0.078,
"amount": "10000",
"maturity": "2025-06-15T00:00:00Z"
}
}
Verification
Verify webhook signatures:
import { CreditKit } from '@centuari/credit-kit';
const signature = req.headers['x-centuari-signature'];
const isValid = CreditKit.verifyWebhook(req.body, signature, WEBHOOK_SECRET);
if (!isValid) {
return res.status(401).json({ error: 'Invalid signature' });
}
Best Practices
Respond Quickly
Return 200 within 5 seconds
Handle Idempotently
Same event may be delivered multiple times
Verify Signatures
Always verify before processing
Log Events
Store for debugging and auditing
Retry Policy
Failed deliveries are retried:
- 1st retry: 1 minute
- 2nd retry: 5 minutes
- 3rd retry: 30 minutes
- 4th retry: 2 hours
- 5th retry: 24 hours
