Webhook

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.

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.

👍

Updating Order Status in your System

As a best practice, we recommend relying on both the webhook and GetPaymentStatus to update your system with the latest status of the transaction.

🚧

Two Webhook Events for the same Transaction

In some rare scenarios, you may receive two webhook events for the same transaction. If the TransactionStatus one of these webhook events is SUCCESS, ignore the other webhook event and mark the order as paid in your system.

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.
5. Recurring Status Changed:
   This will send a webhook event for every deduction attempt on a Recurring Payment. You will find the needed information about this event in the Recurring 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

3. Encode the secret key and ordered data with UTF-8.
4. Encrypt the string using HMAC SHA-256 with the secret key from the portal in binary mode.
5. Encode the result from the previous point with base64.
6. 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.