Webhook

What is the Webhook?

The webhook is a mechanism for one system to notify or send real-time data to another application or server as soon as an event or update occurs. It's a way to enable communication between different applications or services over the Internet. Webhooks are commonly used in various scenarios to enable seamless integration and communication between different services or systems.

Why to use Webhook?

You can enable the Webhook feature to trigger events each time the order status changes at Taly side This feature will recover the lost orders due to connection loss or delayed callbacks.

We use webhooks to notify your application when there is any changes/updates to your the order status.

How Webhooks Work:

1. Setting up Webhooks: To use a webhook, you typically need to create an endpoint URL on your server that will receive incoming data. This is usually an HTTP or HTTPS URL, something like that: https://www.yourwebsite.com/your-endpoint-name

   1. Send the webhook endpoint URL in the "postBackUrl" key of "initiate order" request. (initiate order API)
   2. Make sure your endpoint URL is active and working smoothly, and ready to accept webhooks. (It is recommended that you test the communication, by using a tool like https://webhook.site to see how it works.)
   3. Ensure that your server's firewall allows incoming requests on the webhook URL from out server IP-Address .

2. Event Triggering: When there is a change to an order occurs in this system, we will send an HTTP POST request to the registered webhook URL with relevant data.

3. Data Payload: The data sent in the POST request, also known as the payload, will contain information about the event that occurred. This data is usually in JSON format

   Key	Value
   amount	2.000
   orderToken	34b97f38-4bd6-4880-9f0d-cf1edf0d86a4
   currency	KWD
   orderStatus	CONFIRMED
   merchantOrderId	5827585
   orderDate	2023-08-11T15:50:10.926457

   Json example:-

   JSON

   {
     amount:2.000,
     orderToken:"34b97f38-4bd6-4880-9f0d-cf1edf0d86a4",
     currency:"KWD",
     orderStatus:"CONFIRMED",
     merchantOrderId:"5827585",
     orderDate:"2023-08-11T15:50:10.926457"
   }

4. Webhook Signature: since webhooks involve external systems sending data to your server, security is important. Taly signs the webhook events that send to your endpoints by including a signature in each event’s Taly-Signature header. This allows you to verify that the events were sent by Taly, not by anyone else.

   
   

   You'll get your "Secret Keys" during the onboarding process via email

5. Validation: Use the shared secret key and the same hashing algorithm (HMAC-SHA256) that Taly used to create the signature, Compute the signature for the received payload.

   1. Convert the received payload into JSON Object.
   2. Sort the keys of JSON object in ascending order.
   3. Concatenate the values present against the keys, separated by ‘&’.
   4. Remove first ‘&’ from concatenated string. i-e
      (2.000&34b97f38-4bd6-4880-9f0d-cf1edf0d86a4&KWD&CONFIRMED&5827585&2023-08-11T15:50:10.926457)
   5. Concatenated string is used to calculate the HMAC-SHA256 signature using the provided secretKey.
   6. The resulting signature is converted to a hexadecimal string and returned.

      1. 👍

         If the computed signature matches the one provided in the Taly-Signature header, it means the event is legitimate and has not been tampered with. You can proceed to process the event.

      2. ❗️

         If the signatures do not match, you should reject the event and log the discrepancy as it may indicate a potential security threat or a malformed request.