Finmo uses webhooks to notify your application any time an events happens on your account. You can set up static webhook via the Dashboard. If you do not wish to use the static webhook you can also provide us with a dynamic webhook_url in most of the API that trigger a webhook.

NOTE: Finmo sends the webhook via HTTPS POST so you must provide a HTTPS url. If you do not provide a HTTPS url, Finmo will replace it with https before sending. If it does not find, it returns an error. For HTTPS you need to get a SSL certificate. You can use a tool like ngrok to make your endpoint available for receiving webhooks during testing.

Webhook Retry Logic

Finmo attempts to deliver your webhook six times with exponential backoff between each interval and will stop retrying until we have received response from your server or there is still no response yet. At any point in time, you can still retrigger the webhook manually.

Interval (Relative to first point of failure)	`Retry Number`
15min	1
1hr	2
3hr	3
6hr	4
12hr	5
24hr	6

Webhook Security

Keeping your endpoints secure is critical to protecting your customers' information. Our platform provide few simplistic options to verify events are actually coming from Finmo in a secure manner.

Webhook Custom Header: Finmo can optionally sign the webhook notifications it sends to your endpoints. We do so by including a token in each event's x-security-token header. This allows you to verify that the events were sent by Finmo, not by a third party. You can define your custom header in the dashboard.

IP white-listing: You can white-list Finmo's IP address from where the webhook is originated. Please reach out to our Support team for the IP address.

Webhook Events

We have few built-in events on which the webhooks get triggered.

Refer to the table below for the various EVENT_TYPE and their EVENT_NAME supported on the platform today.

EVENT_TYPE	EVENT_NAME	DESCRIPTION
CHECKOUT	CHECKOUT_CREATED	Checkout page got generated successfully
	CHECKOUT_COMPLETED	Likely that the Payment was made and checkout successfully returned the user to the return urls provided. Always refer to `PAYIN_COMPLETED` if the payment was received by Finmo.
	CHECKOUT_AWAITING_FUNDS	Payment for the checkout has likely been made by user, but Finmo is still awaiting funds from its partner bank.
	CHECKOUT_CANCELLED	Checkout session was cancelled by the user
	CHECKOUT_EXPIRED	Checkout session has expired since the payment was not completed within the validity period that was set during checkout creation.
PAYIN	PAYIN_CREATED	Payment request was successful. You can create using a Hosted Checkout or a Direct API call. The status of the payment will be pending
	PAYIN_COMPLETED	Payment was made by the user. Funds got credited to one of the Finmo's bank account or it's network partners'. All your settlements are based on this
	PAYIN_AWAITING_FUNDS	Payment has likely been made, but Finmo is still awaiting funds from its partner bank (to be deprecated after 14th August 2025)
	PAYIN_SUCCEEDED	The customer’s payment has successfully completed. You can now fulfil the purchased goods or services.
	PAYIN_CANCELLED	Payment was cancelled by the user. Typically follows after Checkout was cancelled
	PAYIN_EXPIRED	Payment instructions got expired
	FEES_PAYMENT	Any payment made to Fee wallet against an invoice raised by Finmo
	TOPUP	Any funds loaded to Payin (typically for refunds) or Payout wallet
VA_PAYIN_COMPLETED	Funds received on a static virtual account
REFUND	REFUND_CREATED	Refund request was created
	REFUND_COMPLETED	Refund request was completed successfully
	REFUND_FAILED	Refund request failed
CUSTOMER	CUSTOMER_CREATED	Customer object created successfully
	CUSTOMER_UPDATED	Customer object was updated. Typically when you update the details such as Address etc
	CUSTOMER_DISABLED (Deprecated)	Customer status object was temporary marked as Disabled
	CUSTOMER_ENABLED (Deprecated)	Customer status object is updated back to Active
	CUSTOMER_DELETED	Customer object is soft deleted on the platform
WALLET	WALLET_CREATED	Wallet object created successfully
VIRTUAL_ACCOUNT	VIRTUAL_ACCOUNT_CREATED	Virtual Account was issued to a customer
	VIRTUAL_ACCOUNT_DELETED	Virtual Account was deleted for a customer
PAYOUT	PAYOUT_CREATED	Payout request was successful
	PAYOUT_COMPLETED	Payout was processed from Finmo's end successfully. This is not an indicator of beneficiary in receipt of funds
	PAYOUT_FAILED	Payout request failed
	PAYOUT_RETURNED	Payout got completed earlier but the funds were returned due to some reason by the beneficiary's bank
WALLET_FUND_TRANSFER	WALLET_FUND_TRANSFER	Wallet fund transfer completed

Webhooks have a two-layer structure:

The outer layer, or wrapper layer, containing basic information about the webhook.
The event_detail object inside the body object, containing the specific information generated by the trigger event.

Body Parameters

Parameter	Type	Description
`webhook_notification_id`	string	Webhook ID
`org_id`	string	Your Finmo organization id
`event_id`	string	Unique id of the event
`event_type`	string	Type of the event for which the webhook has been created
`event_name`	string	Name of the event for which the webhook has been created
`event_description`	string	Description of the event for which the webhook has been created
`webhook_url`	string	URL where the webhook was sent
`event_detail`	JSON	Detail about the corresponding event type
`created_at`	date	UTC date (YYYY-MM-DD).
`updated_at`	date	UTC date (YYYY-MM-DD).
`http_response`	JSON	Response that is received from client while sending webhook notification.
`attempt_count`	Number	Number of attempts made to send webhook notification.
`headers`	JSON	Headers that are sent along with webhook notifications.

Example Webhooks

Checkout

Payin

Refund

Customer

Wallet

Created

Virtual Account

Payout

Wallet Fund transfer

Completed