Introduction

We use webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when a customer’s made a payment, deposit money to your account, refund status changed or supplier account status changed.
You can listen to specific events by webhook as you don’t need to inquiry after these actions to get the response.

❗️

SSL

SSL is required. Ensure that your server is configured to support HTTPS, with a valid server certificate.


How it Works

📘

Portal account

Before you build Your Endpoint, you need to set up your webhook information in your portal account as described in the Webhook Information section.

To receive and process events, you need to set up your server and provide a URL where the webhook can take place. The URL will be something like that:
https://www.yourwebsite.com/your-endpoint-name

MyFatoorah webhook will request your endpoint with a RESTful call. It means your endpoint will receive a JSON body with event data that will be in the following structure.

Input Parameter

Type

Description

EventType

number

1 For Transaction Status Changed
2 For Refund Status Changed
3 For Balance Transferred
4 For Supplier Status Changed
5 For Recurring Status Changed

Event

string

TransactionsStatusChanged
RefundStatusChanged
BalanceTransferred
SupplierStatusChanged

DateTime

datetime

The event date time format "ddMMyyyyHHmmss"

CountryIsoCode

string

The country for the event portal with 3 alpha ISO format

Data

DataModel

The event data model and it depends on the event type. see describtion below.

For now, we support four types of events:

  1. Transaction Status Changed:
    This will notify your system of the transaction status (success, failed). You will find the needed information about this event in the Transaction Data Model section.
  2. Refund Status Changed:
    This will notify your system of the refund status (refunded, canceled). You will find the needed information about this event in the Refund Data Model section.
  3. Balance Transferred:
    This will notify your system of the new deposit whenever Myfatoorah transferred the balance to your bank account. You will find the needed information about this event in the Deposit Data Model section.
  4. Supplier Status Changed:
    This will notify your system of the supplier account status (approved, rejected). You will find the needed information about this event in the Supplier Data Model section.

Webhook Signature

MyFatoorah can optionally sign the webhook events it sends to your endpoints by including a signature in each event’s MyFatoorah-Signature header. This allows you to verify that the events were sent by MyFatoorah, not by a third party.

MyFatoorah recommends this option for security and this option can be configured from the webhook page on your portal by enabling the secure key.

The MyFatoorah-Signature header is included in each signing event, which contains a signature that is encrypted by your secret key.

MyFatoorah generates signatures using a hash-based message authentication code (HMAC) with SHA-256. To prevent downgrade attacks, you should order the data model properties alphabetic with its values then encrypt them by the secret key then compare the generated signature with MyFatoorah-Signature to make sure that this request is from our side.

  1. Order all data properties in alphabetic and case insensitive.
  2. Create one string from the data after ordering it to be like that
    key=value,key2=value2 ...

🚧

If the value of any property is null, replace it with the empty string. See how the customer email is represented in the below example:
CreatedDate=04032021211555,CustomerEmail=,CustomerMobile=96512345678

  1. Encode the secret key and ordered data with UTF-8.
  2. Encrypt the string using HMAC SHA-256 with the secret key from the portal in binary mode.
  3. Encode the result from the previous point with base64.
  4. Compare the signature header with the encrypted hash string. If they are equal, then the request is valid and from the MyFatoorah side.

📘

RefundStatusChanged Event

You should omit the GatewayReference parameter from the Refund data model to generate the correct signature.


Did this page help you?