Webhooks

📡 How Webhooks Work

When an event occurs (e.g., payment status update or deposit confirmation), FV Bank sends an HTTP POST request to your configured webhook URL with event details.

Event Occurs → FV System → Webhook POST → Your Server → Process Event

⚙️ Webhook Setup

To receive webhooks, you must provide a publicly accessible HTTPS endpoint.

• The endpoint must accept POST requests
• It should return a 200 OK response to acknowledge successful receipt
• Non-200 responses will trigger retries

🔐 Webhook Security (Signature Verification)

Each webhook request includes a signature header to verify authenticity.

x-webhook-signature: <signature>

How to verify:

1. Use your webhook secret key
2. Compute HMAC SHA256 of the request payload
3. Compare with the signature header

Example (Node.js):

const crypto = await import('crypto');
const signature = res.headers['x-signature'];
const hmac = crypto.createHmac('sha256', CLIENT_SECRET);
const expectedSignature = hmac.update(JSON.stringify(res.body?.Data)).digest('hex');
const a = Buffer.from(signature);
const b = Buffer.from(expectedSignature);
if (crypto.timingSafeEqual(a, b)) {
    console.log('Matched');
} else {
    console.log('Signature Not Matched');
}
  …

🔁 Retry Mechanism

If your server does not return a 200 OK response:

• The webhook will be retried automatically
• Multiple retry attempts will be made with increasing intervals

Ensure your endpoint is idempotent to safely handle duplicate events

📌 Best Practices

• Verify webhook signatures before processing
• Store processed event IDs to prevent duplication
• Use webhooks for real-time updates and APIs for reconciliation
• Always return 200 OK quickly, then process asynchronously

📌 Summary

Webhooks provide a reliable way to stay updated on:

Payments → Status Updates
Deposits → Confirmation Events

They are essential for building real-time, event-driven integrations.