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. | |
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 page got expired | |
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. | |
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. |