Power of Webhooks in payment gateway integration

You’ve probably seen Webhooks integrations in your applications and you’re wondering what they are and if you should be using them.The answer, in a nutshell, is probably yes.

Webhooks are automated messages sent from apps when something happens. Webhook is a HTTP callback. The callback is done to a URL specified while creating a webhook.The webhook callbacks are event driven i.e. a callback to a webhook will be done whenever the event associated with the webhook occurs. Generally, when you make a request to an API endpoint, you expect to get a near-immediate response. However, some requests may take a long time to process, which can lead to timeout errors. API’s request can fail if the network connection on a customer's device fails or is weak or if the device goes off after a transaction*.* Since your records need to be updated with the final state of the request, you need to either:

• Make a request for an update (popularly known as API) or,

• Listen to events by using a webhook URL.

REAL-TIME: WEBHOOKS vs API

There are two ways your apps can communicate with each other to share information: API and webhooks. In a much simpler way, API is like knocking at your local grocery shop and asking if they have any salt ,but you have to go and ask for it every time you want it. Webhooks are like someone tossing a bag of salt at your house whenever they buy some. You don't have to ask—they just automatically give it to you every time it's available. Here’s another way you can think of it. You know how your phone automatically notifies you when you receive a new message? Webhooks work the same way. If these notifications were turned off, however, you’d have to check for texts yourself every few hours.That’s the way API requests work. Webhooks are always faster than API, and require less work on your end.

API requires making a GET request at regular intervals to get the final status of a request. For example, when a customer makes a payment for a transaction, you keep making a request for the transaction status until you get a successful transaction status.

With webhooks, the resource server, payment gateway in our case, sends updates to your server when the status of your request changes. The change in status of a request is known as an event. You’ll typically listen to these events on a POST endpoint called by your webhook URL.So, instead of the user polling a server asking if the state has changed, the user can only say: "Hey, you know what? You tell me when the state changes".

Note that webhooks are automatic. This helps save time and improve your app experience.

HOW CAN YOU USE WEBHOOKS IN PAYMENT INTEGRATION?

Webhooks are HTTP POST APIs that need to be created at the client’s end. To get started with webhooks, you need to first create certain APIs for listening to different Payouts events and then configuring them at PG side.Webhooks are events that notify you when a transaction changes its status. For example, they can let you know the moment a payment is authorized, refunded, succeeds or fails. This is particularly useful for asynchronous payment flows, in which a transaction may first return a status of Pending before returning a final status indicating the success or failure of the transaction request.

To use Webhooks during integration:

1. Create a server URL from your business server landscape and share it with your PG(payment gateway) like Justpay, Payu, Razorpay . It is the URL at which the transaction response from PG will hit.

    router.post("webhook", async (ctx) => {
      //receiving response
      let data = ctx.request.body;
      console.log( "Webhooks for success transaction" , data)
      // save or modify data as per your requirement
      ctx.response.status = HttpStatusCodes.SUCCESS;
      // responding with 200 ok response to payment gateway
    };
   

2. PG will configure the client’s server URL at its backend, mapping it against the Client ID and key of that particular client.

1. PG will send an S2S response to the client’s server URL. The client’s server URL should be capable of handling the following content types:

   • FormData

   • application/x-www-form-urlencode

Sample response from Payu(PG) to the client server

 {
  "mihpayid": "403993715527978559",
  "mode": "NB",
  "status": "success",
  "key": "*****",
  "txnid": "56072d34-7341-46ad-a955-f58390aa06ca",
  "amount": "96.00",
  "addedon": "2022-12-27 15:16:45",
  "productinfo": "*******",
  "firstname": "*******",
  "lastname": "",
  "city": "",
  "state": "",
  "country": "",
  "zipcode": "",
  "email": "testEmail@poriyaalar.com",
  "phone": "90000000091",
  "udf1": "16717922092431521",
  "field9": "Transaction Completed Successfully",
  "payment_source": "payu",
  "PG_TYPE": "NB-PG",
  "error": "E000",
  "error_Message": "No Error",
  "net_amount_debit": "96",
  "discount": "0.00",
  "unmappedstatus": "captured",
  "hash": "8abbe32b4fc100b314bedd69cf5682c0eaed31a2c6369aa323c958fdb054deb7d8bbce402ac508651f63c0ecd9616eb9e1b63d90c4f3ff6282d9ce45b771ec10",
  "bank_ref_no": "c12635a7-8e2d-4be3-941c-ac87d218b509",
  "bank_ref_num": "c12635a7-8e2d-4be3-941c-ac87d218b509",
  "bankcode": "LVCB"
}

The parameters used in generating the above response block are similar to those you shared with PG while triggering the transaction.

1. Confirm (your server) the receipt with the success status response code: 200 OK after the PG response hits your server URL. PG will attempt three times to get a 200 OK response from client’s servers before flagging the transaction as a timeout.

ERROR HANDLING FOR A ROBUST SYSTEM

One of the essential things to understand when using any web-based system is how the error is being handled. After a webhook delivers data to an application, it may stop paying attention. This can lead to data loss if your application has an error while receiving a message. The key takeaway is understanding how your webhook provider deals with various error responses so you can develop applications with proper error handling. The other problematic aspect of webhooks is the frequency of requests. While webhooks are lightweight, if they’re called thousands of times a second, you can effectively ‘distributed denial-of-service (DDoS) attack’ your own application. Ensuring the app can sustain itself under the load of webhook calls should be part of your application structure.

CLOSING THOUGHT

Understanding webhooks and incorporating them in your backend can help improve your processes, services, and overall your app experience.We hope this makes a well-rounded introductory piece on webhooks. Have you already used webhooks in your apps? Let us know what we missed.