Dispute webhooks notify your endpoint about disputes raised on your payments — when a customer opens a dispute, when you challenge it, and when it is resolved. This lets you react to disputes without polling the Disputes API.
Dispute webhooks cannot be managed through the API. Unlike payment webhooks, they are not registered via the Register a webhook endpoint. To start receiving them, ask the Integrations Team to enable them for your merchant_code and provide your endpoint URL. Disputes have no test mode: dispute webhooks are sent for live payments only (the same as the Disputes API).
Payload
A dispute webhook is a POST request with a JSON body that links the dispute to the affected payment:
{
"status": "pending",
"dispute_id": "string",
"payment_id": "string",
"amount": "100.00",
"currency": "SAR",
"created_at": "2026-06-15T13:08:54Z"
}
| Field | Description |
|---|
status | The dispute event — see Dispute statuses below. |
dispute_id | ID of the dispute. Use it with the Get dispute by ID endpoint to fetch full details. |
payment_id | ID of the payment the dispute was raised against. Use it to correlate the dispute with the order in your system. |
amount | Disputed amount, as a string. The number of decimals follows the currency — SAR and AED use 2 (e.g. "100.00"), KWD uses 3 (e.g. "100.000"). |
currency | ISO currency code of the payment (SAR, AED, KWD). |
created_at | When the dispute was created, in UTC, ISO 8601 datetime format. |
Dispute statuses
The status field tells you what happened to the dispute:
status | Meaning |
|---|
pending | The customer opened a dispute on your payment. |
arbitration | You challenged the dispute (for example, the amount is wrong) and it moved to arbitration. |
evidence_merchant | Tabby support requested supporting evidence from you. |
approved | The dispute was approved and the amount was refunded to the customer. |
declined | The dispute was declined by Tabby support. |
cancelled | The dispute was cancelled by the customer. |
Delivery
Dispute webhooks use the same delivery mechanism as payment webhooks — the same endpoint(s), optional authentication header, retry policy, and server IPs. In particular:
- Acknowledge each delivery with
200 and process it asynchronously — see Best Practices.
- Delivery order is not guaranteed and a notification may occasionally be delivered twice — deduplicate by
dispute_id + status.
- Failed deliveries are retried — see Retry Attempts.
