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

# Webhooks

> Receive real-time updates about your cases

With webhooks, your app can know when something happens in Decisionly, such as a chargeback being filed for a case.

## Registering Webhooks

To register a new webhook, you need to have a URL that Decisionly can call. You can configure a new webhook from your dashboard [settings](https://decisionly.com/settings). Add your URL and pick the events you want to listen for.

## Consuming Webhooks

When you receive a webhook request from Decisionly, check the `type` attribute to see what event caused it.

### Case Lifecycle Events

* `case.created` - Triggered when a case is created
* `case.chargeback_filed` - Triggered when a chargeback is filed with the card network
* `case.chargeback_represented` - Triggered when merchant responds with evidence
* `case.prearb_received` - Triggered when the merchant challenges a dispute via pre-arbitration (Visa allocation flow)
* `case.prearb_filed` - Triggered when a pre-arbitration case is filed with the card network
* `case.prearb_rebutted` - Triggered when a pre-arbitration is rebutted by the merchant
* `case.arbitration_filed` - Triggered when an arbitration case is filed with the card network
* `case.won` - Triggered when a cardholder wins a case
* `case.lost` - Triggered when a cardholder loses a case
* `case.accepted` - Triggered when issuer accepts liability
* `case.rejected` - Triggered when a case is rejected
* `case.expired` - Triggered when a case expires
* `case.withdrawn` - Triggered when a case is withdrawn by the cardholder
* `case.merchant_credited` - Triggered when a case is closed due to merchant credit

You likely want to listen for case lifecycle events to trigger processes in your system such as cardholder communication and money movement.

### Queuing Events

* `case.queued` - Triggered when a case is [queued for filing](/filing#queueing-a-case-that-is-too-early-to-file) because its network waiting period has not passed
*

You may want to listen for case queuing events to trigger automated processes in your system or additional communication with the cardholder.

### Case Needs Review Events

* `case.chargeback_needs_review` - Triggered when a chargeback requires manual review
* `case.representment_needs_review` - Triggered when a representment requires manual review

You may want to listen for case needs review events to trigger manual review processes in your system or additional communication with the cardholder.

### Case Deadline Events

* `case.resolution_deadline_approaching` - Triggered 12 hours before the Reg E or Reg Z resolution deadline if one applies to the case

You may want to listen for case deadline events to ensure you resolve the case before the deadline.

## Webhook Payload

Webhooks do not contain any sensitive information. They only contain the IDs of the objects that were affected by the event. So for case events, the `data` attribute will contain the `case_id`. You should then call the API to fetch the case and verify the event.

### Example Webhook Payload

```json theme={null}
{
  "event_id": "event_2d7448cda095419bbecf066446104e37",
  "created": "2026-04-01T17:36:24.494Z",
  "type": "case.chargeback_filed",
  "data": {
    "case_id": "case_db7fc63f5b6842c1bfb5ffd74b71a66d"
  }
}
```

## Responding to Webhooks

<Info>
  You should return a `200` status code to acknowledge the webhook. If you
  return a different status code, Decisionly will retry the webhook in 30
  minutes, up to 24 times (12 hours of retries).
</Info>