Page tree
Skip to end of metadata
Go to start of metadata

Hi there, I’d like to educate you on our webhook notification and 3 important steps to take when you receive such notifications.


Firstly, when is this webhook notification sent?

When a customer completes a transaction, an API notification is sent to you via your configured webhook URL informing you of the transaction. This notification contains information about the transaction such as transaction reference, payment reference, amount, and customer information. It is expected that your system automatically gives value when this notification is received.

Upon receiving this notification, however, it is imperative that you do the following:

  1. Validate the authenticity of notification by comparing transaction hash.
  2. Call Monnify’s API to confirm transaction status.
  3. Check for duplicate notifications.

STEP 1: Validate authenticity by comparing the hash

To prevent fraudulent notifications to your system which could result in loss of funds, it’s important you verify the source of every notification sent to you.

Every notification from Monnify to you contains a hash; which is generated using your API Key and Secret. To confirm the authenticity of a notification, recompute the transaction hash following instructions described here, and compare your result with the hash in the notification payload. A mismatch in computed hash means the transaction is not from Monnify and should not be honored.

A match means the notification is authentic and you should proceed to step 2.


STEP 2: Call Monnify’s API to confirm transaction status

Upon validating the authenticity of a notification, it is highly recommended to call Monnify again to get the status of the transaction. This is another step in validating the authenticity of notification and will protect you should your API keys be compromised and a malicious user able to generate a valid hash. Requests to get transaction status will fail if the supplied reference is not a valid reference on Monnify, and you can also check the payment status in the response from this API to confirm that payment was successful.

To do this, you can call this endpoint - Get Transaction Status.

STEP 3: Check for duplicate notifications

Lastly, multiple notifications may be sent when Monnify is not able to confirm that you’ve received a previous notification due to system or network errors from either party, in which case, Monnify resends the notification until a successful acknowledgment is received.

As this notification is the trigger for giving value to your customer, it is important to keep track of notifications you’ve already received and processed so as not to erroneously give value to a customer multiple times. Upon receipt of every notification, ALWAYS check to make sure you have not received nor processed this notification before going ahead to give customer value. A unique identifier in the request payload that can be used for this check is “transactionReference”.