Webhook Version V1

Webhooks are events that notify you about the payment status. All Payout integrations should establish a webhook to listen to payout events, like status changes on payments. Webhooks are HTTP callbacks that receive notification messages for events.

Webhooks help you receive automatic updates and are significant for completing the integration with Telr. Webhooks are triggered with a request from your side, for example, when a transfer fails or when a daily report is available. Requests get processed both synchronously and asynchronously. In rare scenarios, for some payment methods, the outcome may take a longer duration to confirm. Telr notifies you once we get updates from the bank about the payment status.

Do not go live without signature verification if you are using webhooks.

​

Add a webhook

Follow the instructions below to configure webhooks for version 2 APIs:

1. Log in to the Payouts dashboard using your credentials.
2. Navigate to Developers > Webhooks.
3. Click Add Webhook URL in the Webhooks page.
4. In the Add Webhook popup, enter the following information:
   • Webhook URL - Enter the URL where you want to receive the transfer related notifications.
   • Select a webhook version - Select V1 from the dropdown menu.
5. Click Test & Add Webhook.

​

Webhook events

Payouts webhooks enable you to receive updates about all event-driven activities originating from your account. Below is the list of payouts webhooks:

​

TRANSFER_SUCCESS​

Sent when a transfer is attempted successfully at the bank and the beneficiary account is credited.

​

What does the response parameter ‘acknowledged’ mean?

The acknowledged parameter value conveys if the beneficiary received the funds by checking its value. Ack = 1 or 0 . 1 denotes the beneficiary received funds, and 0 denotes the beneficiary had not received funds.

The cash flow happens as explained below:

1. Debit: The debit of the transfers happens on the remitter account. After a successful debit, the beneficiary bank does further processing. When only the debit is successful, Ack = 0.

2. Credit: The beneficiary bank credits the fund to the account. The transfer is sent from the remitter bank to the beneficiary bank after a successful debit. When the credit to the end beneficiary is successful, Ack = 1.

To confirm the status of a payout, you need to check the acknowledged parameter value. If the value is 1, you can mark the transfer as successful. However, if the value is 0, you must either wait for the TRANSFER_ACKNOWLEDGED webhook event or use the Get Transfer Status API and confirm the acknowledged value.

​

​TRANSFER_FAILED

Sent when a transfer attempt fails.

​

TRANSFER_REVERSED

Sent when the beneficiary bank reverses a transfer.

​

CREDIT_CONFIRMATION

Sent when the balance credit is confirmed.

​

TRANSFER_ACKNOWLEDGED

Sent when the bank acknowledges a transfer.

​

TRANSFER_REJECTED

Sent when a transfer is rejected.

​

BENEFICIARY_INCIDENT

Sent when a beneficiary incident is created or resolved.

​

LOW_BALANCE_ALERT

Sent when the payout balance is low.

​

BULK_TRANSFER_REJECTED

Sent when one of the transfers in the batch transfer file has been rejected.

Delay in Receiving the Response

Telr receives a response from the bank with the status of the transfer instantly. At times the response may get delayed due to various reasons, and the transaction status will be marked as Pending, till we get a response.

Telr polls the transaction status from the bank for the next 72 hours. In case we do not receive the status of a transaction after 72 hours, the transaction needs to be manually reconciled.

​

Signature Verification

Telr sends a signature alongside every webhook, verifying this signature ( passed along with the POST parameters ) is mandatory before processing any response. It helps authenticate that the webhook is from Telr.

We strongly recommend whitelisting Telr production IP to help make your communication with us more secure.

Following are the steps to verify Telr signature:

1. Get all the POST parameters except ‘signature’ and assign it to an array as key-value pair.
2. Sort the array based on keys.
3. Concatenate all the values in this array and resultant is the post data (say, postData).
4. postData needs to be encrypted using SHA-256, and then base64 encoded.
5. Now verify if both the signature calculated and the signature received match.
6. Proceed further if it matches, else discards the request.

Our libraries also support signature verification. To verify the signature returned by Telr call the following methods from the library.

Below are the code snippets that can help you verify the signature:

<?php
  $data = $_POST;
  $signature = $_POST["signature"];
  unset($data["signature"]); // $data now has all the POST parameters except signature
  ksort($data); // Sort the $data array based on keys
  $postData = "";
  foreach ($data as $key => $value){
    if (strlen($value) > 0) {
      $postData .= $value;
    }
  }
  $hash_hmac = hash_hmac('sha256', $postData, $clientSecret, true) ;
  
  // Use the clientSecret from the oldest active Key Pair.
  $computedSignature = base64_encode($hash_hmac);
  if ($signature == $computedSignature) {
    // Proceed based on $event
  } else {
    // Reject this call
  }
?>

​

Webhook Retries

Telr webhooks service does its best to deliver events to your webhook endpoint. It is best practice for your application to respond to the callback. Our webhook service may send many payloads to a single endpoint in quick succession. You will need to build an application and configure your server to receive the response we send when events get triggered during the payout process.

Your server should return a 200 HTTP status code to acknowledge that you received the webhook without any issues. Any other information you return in the request headers or request body gets ignored. Any response code outside the 200 range, including 3xx codes, indicates that you did not receive the webhook.

When Telr does not get the acknowledgement due to any reason, we retry to establish the communication at regular intervals. If we do not receive the response after few attempts, we gradually decrease the rate of retries. Based on this count, the service is disabled if it fails more than five times.

If do not receive notifications from Cashfree Payments as expected, please fill out the Support Form.

​

IPs to whitelist

When you decide to consume the webhooks, first, you need to verify if your systems need an IP whitelisting to be done at your end or not. Accordingly you can whitelist the below IPs of Telr:

UAT:
52.66.25.127
15.206.45.168

Prod:
52.66.101.190
3.109.102.144
3.111.60.173
18.60.134.245
18.60.183.142

Port: 443 (Secured)