FinFusion

Webhooks

Receive real-time notifications for events in your FinFusion integration

Webhook URLs

Configure your webhook endpoints in the FinFusion Dashboard

Overview

Webhooks allow your application to receive real-time notifications when events occur in your FinFusion account. Instead of polling our API, webhooks push events to your specified endpoints as they happen.

Setting Up Webhooks

1. Configure Endpoint

Add your webhook endpoint URL in the FinFusion Dashboard. We recommend using HTTPS for security.

2. Implement Verification

Verify webhook signatures to ensure events are from FinFusion:

webhook-handler.js 
// Express.js example
const express = require('express');
const app = express();

app.post('/webhooks', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-finfusion-signature'];
  
  try {
    const event = finfusion.webhooks.constructEvent(
      req.body,
      signature,
      'whsec_your_webhook_secret'
    );
    
    // Handle the event
    switch (event.type) {
      case 'payment.succeeded':
        const payment = event.data.object;
        handlePaymentSuccess(payment);
        break;
      // ... handle other events
    }

    res.json({received: true});
  } catch (err) {
    console.error('Webhook error:', err.message);
    res.status(400).send(`Webhook Error: ${err.message}`);
  }
});

3. Handle Events

Process webhook events based on their type and update your application accordingly.

Event Types

Payment Events

Event Description
payment.succeeded Payment was successfully processed
payment.failed Payment attempt failed
payment.refunded Payment was refunded
payment.disputed Payment was disputed by customer

Banking Events

Event Description
account.created New bank account created
account.updated Bank account details updated
transfer.succeeded Transfer completed successfully
transfer.failed Transfer failed to process

Card Events

Event Description
card.created New card issued
card.activated Card was activated
card.blocked Card was blocked
card.transaction Card transaction occurred

Event Payload Structure

event-payload.json 
{
  "id": "evt_123456789",
  "type": "payment.succeeded",
  "created": 1634567890,
  "data": {
    "object": {
      "id": "pay_123456789",
      "amount": 1000,
      "currency": "USD",
      "status": "succeeded",
      "created": 1634567890
    }
  }
}

Security

Signature Verification

Each webhook request includes a signature in the x-finfusion-signature header. Verify this signature to ensure the request came from FinFusion.

HTTPS Required

Webhook endpoints must use HTTPS in production to ensure secure data transmission.

Timeout Handling

Webhook requests timeout after 10 seconds. Ensure your endpoint responds within this timeframe.

Retry Logic

If your endpoint fails to respond with a 2xx status code, we'll retry the webhook using the following schedule:

  • 1st retry: 5 minutes after initial failure
  • 2nd retry: 30 minutes after first retry
  • 3rd retry: 2 hours after second retry
  • 4th retry: 12 hours after third retry
  • 5th retry: 24 hours after fourth retry

Testing Webhooks

Test your webhook integration using our webhook testing tools:

webhook-testing.js 
// Using the SDK to trigger test webhook events
await finfusion.webhooks.trigger({
  type: 'payment.succeeded',
  data: {
    amount: 1000,
    currency: 'USD'
  }
});

Testing Tools

Use tools like webhook.site or ngrok for local webhook testing.

Questions about webhooks? Contact us at support@finfusion.cloud