> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tabby.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Dispute webhooks

> Get notified when a dispute is opened on your payment and when its status changes: payload, statuses, and delivery.

Dispute webhooks notify your endpoint about <a href="/pay-in-4-custom-integration/disputes">disputes</a> 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 <a href="/api-reference/disputes/get-disputes-list">Disputes API</a>.

<Warning>
  Dispute webhooks **cannot be managed through the API**. Unlike <a href="/pay-in-4-custom-integration/webhooks">payment webhooks</a>, they are not registered via the [Register a webhook](/api-reference/webhooks/register-a-webhook) endpoint. To start receiving them, **ask the Integrations Team to enable them** for your `merchant_code` and provide your endpoint URL.
</Warning>

<Note>
  Disputes have **no test mode**: dispute webhooks are sent for live payments only (the same as the Disputes API).
</Note>

## Payload

A dispute webhook is a POST request with a JSON body that links the dispute to the affected payment:

```JSON theme={"dark"}
{
  "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](#dispute-statuses) below.                                                                                  |
| `dispute_id` | ID of the dispute. Use it with the <a href="/api-reference/disputes/get-dispute-by-id">Get dispute by ID</a> 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 <a href="/pay-in-4-custom-integration/webhooks#best-practices">Best Practices</a>.
* Delivery order is not guaranteed and a notification may occasionally be delivered twice — deduplicate by `dispute_id` + `status`.
* Failed deliveries are retried — see <a href="/pay-in-4-custom-integration/webhooks#retry-attempts">Retry Attempts</a>.