Your server shouldn't use up resources continuously polling Monnify if a transaction is completed. Instead, Monnify uses Webhooks to notify your server directly the moment 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 Changes (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 originated from Monnify before processing anything of value. Two security layers are required:

1. Verify the Webhook Signature: Every valid Monnify webhook includes a signature header. Hash the payload using your Client Secret Key and confirm it matches the signature in the header. Reject any mismatch immediately.
2. Whitelist Monnify's IP Address: To prevent bad actors from sending fraudulent requests to your webhook URL, whitelist Monnify’s IP address on your server. Monnify webhook notifications will only originate from: 35.242.133.146. Drop requests from a different origin.

Acknowledgement And Timeouts

When Monnify sends a webhook, we expect your server to acknowledge receipt promptly.

1. Return a 200 OK response to confirm the webhook was received.
2. Respond before the timeout. If your server performs heavy processing (such as querying slow databases) before sending the 200 OK response, the request may time out on our end.
3. If there is no response, the request will retry. Expect retries if we do not receive the expected response, we assume you did not receive the webhook and will retry every 5 minutes, up to 12 times.

Best Practice: Receive the webhook, verify its authenticity, return the 200 OK response, then handle any heavy processing asynchronously in the background.

Idempotency: Handling Duplicate Webhooks

Network fluctuations can occasionally cause your server to receive duplicate webhook notifications for the same transaction. Here’s how to handle such:

1. When a webhook arrives, always check whether that event has already been processed.
2. If it has, discard it, but still return the expected status code so Monnify knows to stop retrying.

Developer Tip: Cache your processed notifications or maintain a dedicated "Processed Transactions" log in your database. This makes duplicate checks fast and keeps your integration resilient under load.