Lightweight Integration and Webhooks

The Business Events pipeline delivers events to Kafka or ActiveMQ - both mature, reliable technologies, but both require dedicated infrastructure to run and operate. For some integration scenarios, this is more than necessary.

This page covers the alternatives for teams who need to react to Fineract events without running a message broker, and explains when the full pipeline is the right choice.

Fineract Does Not Have Built-In Webhooks

Apache Fineract does not have a native webhook mechanism - it cannot push an HTTP POST to a URL of your choice when a loan is approved. All real-time event delivery goes through the business events pipeline (Kafka or JMS).

If you need event-driven integration without a broker, the options below cover the practical paths.

Option 1 - Polling the Fineract API

For integrations that do not need sub-minute latency, polling the Fineract API on a schedule is the simplest approach.

How it works: Your integration service calls a Fineract API endpoint on a timer (every 1, 5, or 15 minutes). It compares what it finds against what it last processed and takes action on anything new.

Good for:

• Syncing new clients to a CRM once a day or hour
• Generating end-of-day reports
• Checking loan status for a dashboard that refreshes periodically
• Triggering welcome emails for clients activated in the last hour

Endpoints useful for polling:

# New clients activated after a given date
GET /clients?activatedOnDateFrom=2024-03-15&activatedOnDateTo=2024-03-15

# Loans disbursed after a given date
GET /loans?expectedDisbursementDateFrom=2024-03-15

# Recent journal entries (for accounting sync)
GET /journalentries?fromDate=2024-03-15&toDate=2024-03-15

Most listing endpoints accept date filter parameters. Combine fromDate/toDate or activatedOnDateFrom/activatedOnDateTo filters with pagination to fetch only what changed since the last poll.

Limitations: Not suitable for anything requiring near-real-time response (customer notifications, fraud detection, collection triggers). Polling creates repeated API load. Detecting deletions or reversals requires additional logic.

Option 2 - An Integration Middleware Bridge

If your existing integration platform (MuleSoft, Apache Camel, Azure Logic Apps, AWS Step Functions, n8n, Zapier for business, or a custom middleware) supports scheduled polling and HTTP connectors, you can build a bridge:

1. Middleware polls Fineract API on a schedule
2. Middleware filters and transforms the data
3. Middleware delivers to the target system (CRM, SMS gateway, ERP, data warehouse)

This keeps all integration logic outside Fineract and requires no changes to the Fineract deployment. It is the right pattern when:

• Your integration platform is already established and managed
• The use case does not require real-time delivery
• The number of events per poll interval is manageable (hundreds, not thousands)

Option 3 - Kafka or JMS With a Managed Cloud Broker

If you need real-time events but do not want to run broker infrastructure yourself, managed cloud services remove the operational burden:

• Amazon MSK (Kafka) or Amazon MQ (ActiveMQ/RabbitMQ) - fully managed, no cluster to operate
• Confluent Cloud - managed Kafka with a generous free tier and a simple setup
• CloudAMQP - managed RabbitMQ (note: Fineract's JMS connector targets ActiveMQ specifically)

With a managed broker, the full business events pipeline is available and Fineract publishes events in real time. Your integration service subscribes to the broker - no polling, no missed events, no duplicates (with idempotency key tracking).

This is the recommended path for:

• Customer notifications (SMS, WhatsApp, push) on loan approval, disbursement, repayment
• Real-time CRM updates
• Collection triggers on overdue events
• Fraud monitoring
• Any use case where latency matters

See the Kafka Connector or ActiveMQ Connector guide for setup details.

Option 4 - A Thin Webhook Proxy Service

If your target system expects incoming HTTP webhooks (e.g. a Slack webhook URL, a Zapier trigger endpoint, or a simple Express.js service), you can build a thin proxy:

1. Subscribe to Fineract events via Kafka or JMS
2. For each event, make an outbound HTTP POST to the target webhook URL
3. Handle retries and failures in the proxy layer

This proxy can be a simple Node.js, Python, or Go service. It does not need to be stateful - the broker handles durability and retry until the consumer (your proxy) acknowledges the message.

Open-source tools like Camel K, Knative Eventing, or AWS EventBridge Pipes can serve this role without custom code in some environments.

Choosing the Right Approach

Scenario	Recommended approach
Daily or hourly sync to CRM / ERP	Polling
End-of-day report generation	Polling or scheduled API call
Real-time customer notification on loan events	Kafka/JMS + managed broker
Fraud detection requiring second-by-second feeds	Kafka/JMS + managed broker
Collection trigger on overdue charge	Kafka/JMS + managed broker
Posting to a Slack channel on new client	Kafka/JMS + thin webhook proxy
Your platform has an existing HTTP connector	Polling via integration middleware
You want no infrastructure at all	Polling (accept the latency trade-off)

The Internal Events API

Fineract also exposes an internal read API for the event log stored in m_external_event. This allows you to inspect what events have been recorded and their delivery status:

curl https://your-instance.finecko.com/fineract-provider/api/v1/internalevents \
  -H "Fineract-Platform-TenantId: default" \
  -H "Authorization: Basic $(echo -n 'mifos:password' | base64)"

This is primarily useful for debugging the business events pipeline (checking whether an event was captured and dispatched), not for building integrations.