Your server shouldn't use up resources constantly asking Monnify if a transaction is completed. Instead, Monnify uses Webhooks to actively notify your server once a transaction is executed.

Supported Webhook Events

An “event” refers to the change in status of a request. Monnify will push real-time responses to your server for the following events:

1. Successful Payment
2. Payouts (Disbursements): Successful Disbursement, Failed Disbursement, Reversed Disbursement.
3. Refunds: Successful Refund, Failed Refund.
4. Settlements & Wallets: Settlement Completion (successful transfers to your bank account), Wallet Activity Notification (credits and debits to your Main or Sub-Wallets).
5. Mandate Status Change (e.g., from PENDING to ACTIVATED, FAILED, or CANCELLED).

Security when Dealing with Webhooks

When your server receives a webhook, you must verify that it actually came from Monnify before processing any value. You have to implement these two security layers:

1. Verify the Webhook Signature: Every valid webhook contains a signature header. You must hash the payload using your Client Secret Key and ensure it matches the signature sent in the header.
2. IP Whitelisting: To prevent bad actors from sending fake requests to your webhook URL, you must whitelist our exact IP address on your server. Monnify webhook notifications will only come from this IP: 35.242.133.146. Drop requests from any other origin.

Acknowledgement & Timeouts

When Monnify sends a webhook, we wait for your server to acknowledge that it was received.

1. You must acknowledge receipt of the webhook by returning a standard 200 OK HTTP status code.
2. Monnify webhook requests time out within a few seconds. If your server is doing heavy background processing (like generating PDF receipts or querying slow databases) before sending the 200 OK response, the Monnify server may time out.
3. If we do not get the expected response, we assume you did not receive the webhook and will retry after 5 minutes.

Best Practice: Receive the webhook, verify the authenticity, return the 200 OK response while delegating your heavy processing in the background.

Idempotency (Handling Duplicates)

Sometimes, network fluctuations happen so your system could receive duplicate webhooks for the exact same transaction. Here’s how to handle such:

1. When you receive a new webhook, always check to ensure that event has not been processed.
2. If you have already processed that event, disregard it. However, you must still return the expected status code so Monnify knows to stop retrying.

Pro-Tip for Developers: We heavily advise caching your processed notifications or maintaining a strict "Processed Transactions" log in your database to make these duplicate checks fast.