Dispute webhooks can be configured to receive automated notifications when disputes are created, updated and closed.

The webhook notification will be sent on all the URLs added and enabled under the dispute webhook. Merchants can add new URLs and enable or disable existing URLs for refund webhook at any point in time and it will be reflected instantaneously.

WebhookDescription
DISPUTE_CREATEDDispute_created webhook will be triggered when a new dispute is created.
DISPUTE_UPDATEDDispute_updated webhook will be triggered when a dispute is updated, for example when a comment is added by the Telr team, when the dispute moves into further stages like Pre-arbitration, Arbitration, or when the status of the dispute changes.
DISPUTE_CLOSEDThis webhook will be triggered when a dispute is closed.

Click here to know how to configure webhooks.

​
Dispute Created

Sample Payload

Version 2025-01-01

{
  "data": {
    "dispute": {
      "dispute_id": "433475258",
      "dispute_type": "DISPUTE",
      "reason_code": "1402",
      "reason_description": "Duplicate Processing",
      "dispute_amount": 3,
      "created_at": "2023-06-15T21:49:48+05:30",
      "updated_at": "2023-06-15T21:49:48+05:30",
      "respond_by": "2023-06-18T23:59:59+05:30",
      "dispute_status": ""DISPUTE_CREATED"",
      "cf_dispute_remarks": "Dispute is created, please take action",
      "dispute_action_on": "MERCHANT",
      "dispute_amount_currency": "INR"
    },
    "order_details": {
      "order_id": "order_1944392DR1kMTFYdIf8bI2awAcC3i9FTa",
      "order_amount": 3,
      "order_currency": "INR",
      "cf_payment_id": 885473311,
      "payment_amount": 3,
      "payment_currency": "INR"
    },
    "customer_details": {
      "customer_name": "Dileep Kumar s",
      "customer_phone": "8000000000",
      "customer_email": "dileep@gmail.com"
    }
  },
  "event_time": "2023-06-15T21:50:04+05:30",
  "type": "DISPUTE_CREATED"
}

​
Dispute Updated

Sample Payload

Version 2025-01-01
{
  "data": {
    "dispute": {
      "dispute_id": "433475257",
      "dispute_type": "PRE_ARBITRATION",
      "reason_code": "13.1",
      "reason_description": "Merchandise / Services Not Received",
      "dispute_amount": 40000,
      "created_at": "2023-06-15T21:16:03+05:30",
      "updated_at": "2023-06-15T21:19:15+05:30",
      "respond_by": "2023-06-19T23:59:59+05:30",
      "dispute_status": "PRE_ARBITRATION_CREATED",
      "cf_dispute_remarks": "Pre Arbitration request has been raised for this case.\nTarget Date :: 2023-06-18T00:00 -> 2023-06-19T23:59:59.",
      "dispute_update": "TYPE_UPDATE",
      "dispute_action_on": "MERCHANT",
      "dispute_amount_currency": "INR"
    },
    "order_details": {
      "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
      "order_amount": 40000,
      "order_currency": "INR",
      "cf_payment_id": 885457437,
      "payment_amount": 40000,
      "payment_currency": "INR"
    },
    "customer_details": {
      "customer_name": "Dileep Kumar s",
      "customer_phone": "8000000000",
      "customer_email": "dileep@gmail.com"
    }
  },
  "event_time": "2023-06-15T21:20:24+05:30",
  "type": "DISPUTE_UPDATED"
}

​
Dispute Closed

Sample Payload

Version 2025-01-01
{
  "data": {
    "dispute": {
      "dispute_id": "433475257",
      "dispute_type": "CHARGEBACK",
      "reason_code": "4855",
      "reason_description": "Goods or Services Not Provided",
      "dispute_amount": 4500,
      "created_at": "2023-06-15T21:16:03+05:30",
      "updated_at": "2023-06-15T21:16:51+05:30",
      "respond_by": "2023-06-18T00:00:00+05:30",
      "resolved_at": "2023-06-15T21:16:51.682836678+05:30",
      "dispute_status": "CHARGEBACK_MERCHANT_WON",
      "cf_dispute_remarks": "Chargeback won by merchant",
      "dispute_amount_currency": "INR"
    },
    "order_details": {
      "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
      "order_amount": 4500,
      "order_currency": "INR",
      "cf_payment_id": 885457437,
      "payment_amount": 4500,
      "payment_currency": "INR"
    },
    "customer_details": {
      "customer_name": "Dileep Kumar s",
      "customer_phone": "8000000000",
      "customer_email": "dileep@gmail.com"
    }
  },
  "event_time": "2023-06-15T21:17:14+05:30",
  "type": "DISPUTE_CLOSED"
}

​
Payload Field Description

FieldDescriptionExampleType
dispute_idTelr’s unique ID to identify a dispute.433475257Long
dispute_typeType of dispute created. Possible values:
- DISPUTE
- RETRIEVAL
- CHARGEBACK
- PRE_ARBITRATION
- ARBITRATION		ChargebackString
reason_codeCondition for which the customer is filing the case. Click here to know more about dispute reason codes.13.6String
reason_descriptionDescription of the reason code. Codes for Chargeback cases are specified by Card networks/NPCI.Credit not processedString
dispute_amountThe amount for which the dispute has been created.4500BigDecimal
created_atTime on which the dispute was registered on Telr’s system.2023-06-15T21:16:03+05:30LocalDateTime
updated_atTime on which the dispute was updated.2023-06-15T21:16:51+05:30LocalDateTime
respond_byTime by which the merchant is expected to respond to the dispute.2023-06-18T00:00:00+05:30LocalDateTime
dispute_statusStatus of Dispute. All possible values are listed in the table below.CHARGEBACK_CREATEDString
cf_dispute_remarksAny remarks specified by Telr on the dispute.Please submit documents.String
dispute_updateSpecifies what has been updated on the dispute. Possible Values:
- STATUS_UPDATE
- TYPE_UPDATE
- COMMENT_UPDATE		TYPE_UPDATEString
dispute_action_onSpecifies whether the action is on Telr or Merchant at a time. Possible Values:
- MERCHANT
- CASHFREE		MERCHANTString
resolved_atTime on which the dispute was resolved/closed.2023-06-15T21:16:51.682836678+05:30LocalDateTime
event_timeTime at which dispute webhook was initiated.2023-06-15T21:16:51+05:30LocalDateTime
typeType of webhook. Possible Values:
- DISPUTE_CREATED
- DISPUTE_UPDATED
- DISPUTE_CLOSED		DISPUTE_CREATEDString
List of Dispute Status
DISPUTE_CREATED
DISPUTE_DOCS_RECEIVED
DISPUTE_UNDER_REVIEW
DISPUTE_MERCHANT_WON
DISPUTE_MERCHANT_LOST
DISPUTE_MERCHANT_ACCEPTED
DISPUTE_INSUFFICIENT_EVIDENCE
RETRIEVAL_CREATED
RETRIEVAL_DOCS_RECEIVED
RETRIEVAL_UNDER_REVIEW
RETRIEVAL_MERCHANT_WON
RETRIEVAL_MERCHANT_LOST
RETRIEVAL_MERCHANT_ACCEPTED
RETRIEVAL_INSUFFICIENT_EVIDENCE
CHARGEBACK_CREATED
CHARGEBACK_DOCS_RECEIVED
CHARGEBACK_UNDER_REVIEW
CHARGEBACK_MERCHANT_WON
CHARGEBACK_MERCHANT_LOST
CHARGEBACK_MERCHANT_ACCEPTED
CHARGEBACK_INSUFFICIENT_EVIDENCE
PRE_ARBITRATION_CREATED
PRE_ARBITRATION_DOCS_RECEIVED
PRE_ARBITRATION_UNDER_REVIEW
PRE_ARBITRATION_MERCHANT_WON
PRE_ARBITRATION_MERCHANT_LOST
PRE_ARBITRATION_MERCHANT_ACCEPTED
PRE_ARBITRATION_INSUFFICIENT_EVIDENCE
ARBITRATION_CREATED
ARBITRATION_DOCS_RECEIVED
ARBITRATION_UNDER_REVIEW
ARBITRATION_MERCHANT_WON
ARBITRATION_MERCHANT_LOST
ARBITRATION_MERCHANT_ACCEPTED
ARBITRATION_INSUFFICIENT_EVIDENCE

​
Compute Signature and Verify

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Telr PG secret key along with the payload. Timestamp is present in the header x-webhook-timestamp

timestamp := 1617695238078;  
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));```

​
Sample Code

​
Verify Signature using SDK


var express = require('express')
import { Telr } from "cashfree-pg"; 
var app = express()

Cashfree.XClientId = "<x-client-id>";
Cashfree.XClientSecret = "<x-client-secret>";
Cashfree.XEnvironment = Cashfree.Environment.SANDBOX;

app.post('/webhook', function (req, res) {
    try {
        Telr.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"]))
    } catch (err) {
        console.log(err.message)
    }
})

​
Compute Signature and Verify manually


function verify(ts, rawBody){
    const body = req.headers["x-webhook-timestamp"] + req.rawBody;
    const secretKey = "<your secret key>";
    let genSignature = crypto.createHmac('sha256',secretKey).update(body).digest("base64");
    return genSignature
}