Hooks

Receiving Webhooks

In order for MifosX to send webhook payloads, your server needs to be accessible from the Internet.

MifosX will send the response of the event as the request body (in the requested format - json/ x-www-url-formencoded).

For example :-

A successful POST to /clients endpoint will generate the response {"officeId":1,"clientId":1787,"resourceId":1787}.

An action like pay charge (https://demo.openmf.org/mifosng-provider/api/v1/savingsaccounts/382/charges/241?command=paycharge) will generate the response {"officeId":187,"clientId":7,"savingsId":382,"resourceId":241}.

Webhook Headers

MifosX will send along a few HTTP headers to differentiate between event types.

Name	Description
X-Mifos-Entity	The entity type that was triggered.
X-Mifos-Action	The action triggered on the entity type.
X-Mifos-Platform-TenantId	The tenant which experienced the event.

The bridge / third-party app is expected to authenticate with the MifosX server first and send the auth token along with each request to fetch additional information such as client's mobile number or account number.

See /hooks/template response (groupings array inside the json) or the m_permission table (other than special, read and checker permissions) to find a list of all available combinations of Entity and Action.

SMS Bridge Template

You need to clone https://github.com/mgeiss/mifos-twilio-bridge and do a gradlew bootRun to start the application which will act as a bridge between MifosX and Twilio.

So for the Sms Bridge template in the Create Hook form, you need to give http://localhost:9191/modules/sms as the payload url, type "twilio" as the sms provider (without the quotes) and fill the remaining 3 fields (Phone Number, SMS Provider Account Id, SMS Provider token) with the details you received when registering an account in Twilio.

Troubleshooting :

Do not create a SMS Bridge hook with your own mobile number if you have not registered for Twilio. This will cause a wrong api key to be generated by the bridge which will be stored in MifosX. To correct that, you will need to delete the hook in MifosX and manually generate a DELETE request to mifos-twilio-bridge to delete the api key since it won't allow multiple api keys per tenant.

If you create multiple clients in Mifos X with the same mobile number for testing (by deleting the client and creating a new one), that might not be supported by the bridge application because of unique mobile number constraints.

If you somehow lose/clear the db contents for bridge application, it is better to delete the hook in MifosX and create a new one as the bridge application won't find the api key of the old hook in it's db.

If you get a hsqldb lock exception, make sure you are not trying to access from 2 places at the same time by closing any sql editor, hsqldb ide plugins, other services that might be using it, etc.

INFO: The only 2 events in Mifos X currently supported by the bridge application are CREATE CLIENT and REPAYMENT LOAN. The bridge application won't react to other events registered for the SMS Bridge Hook. As of now, it is only meant for demo purposes as specialists can implement their own preferred SMS service provider using the WEB template for hook.