# Update status

> Updates the status of an alert received by webhook.

Página: https://doc.rapidchargeback.com/en/callback/atualizar-status/

Updates the status of an alert received by webhook.

## Endpoint

```
PATCH https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts/:id/status
```

## Authentication

```
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
```

---

## URL parameter

| Parameter | Type | Description |
|---|---|---|
| `id` | string (UUID) | `alert_id` received in the webhook payload |

---

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | Yes | One of three values: `notfound`, `account_suspended`, `other` |

---

## Validations

- `status` must be exactly one of the three valid values; anything else returns `422`
- The alert must belong to your company; otherwise it returns `404`
- Final statuses (`notfound`, `account_suspended`) cannot be changed once sent; trying returns an error
- The `expired` status is set automatically by the system after 24h with no response (Ethoca) and is not sent by the customer
- The only transition allowed after the initial response is `other → account_suspended`, available for up to 6 days (Ethoca)

See [Rules and deadlines](https://doc.rapidchargeback.com/en/produtos/alerta/regras-e-prazos/) for the full detail.

---

## Request example

The credentials come from environment variables (`RAPID_CLIENT_ID` and `RAPID_CLIENT_SECRET`), never written in the code.

**cURL**

```bash
curl -X PATCH https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts/00000000-0000-0000-0000-000000000099/status \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "account_suspended"
  }'
```

**Node.js**

```javascript
const credentials = Buffer.from(`${process.env.RAPID_CLIENT_ID}:${process.env.RAPID_CLIENT_SECRET}`).toString('base64')
const alertId = '00000000-0000-0000-0000-000000000099'

const response = await fetch(`https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts/${alertId}/status`, {
  method: 'PATCH',
  headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ status: 'account_suspended' }),
})

const body = await response.json()
if (!response.ok) throw new Error(`${response.status} ${body.error.code}: ${body.error.message}`)

console.log('Status updated:', body.data.status)
```

**Python**

```python
import os

import requests

alert_id = "00000000-0000-0000-0000-000000000099"

response = requests.patch(
    f"https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts/{alert_id}/status",
    auth=(os.environ["RAPID_CLIENT_ID"], os.environ["RAPID_CLIENT_SECRET"]),
    json={"status": "account_suspended"},
    timeout=30,
)

body = response.json()
if not response.ok:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")

print("Status updated:", body["data"]["status"])
```

**PHP**

```php
<?php
$alertId = '00000000-0000-0000-0000-000000000099';

$ch = curl_init("https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts/$alertId/status");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_USERPWD => getenv('RAPID_CLIENT_ID') . ':' . getenv('RAPID_CLIENT_SECRET'),
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['status' => 'account_suspended']),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException('Network error: ' . curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$body = json_decode($raw, true);

if ($status >= 400) {
    throw new RuntimeException("$status {$body['error']['code']}: {$body['error']['message']}");
}

echo 'Status updated: ', $body['data']['status'], PHP_EOL;
```

---

## Response examples

### Success

```json
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000099",
    "status": "account_suspended",
    "updated_at": "2026-04-14T14:30:00.000Z"
  }
}
```

### Alert not found

```json
{
  "error": {
    "code": "ALERT_NOT_FOUND",
    "message": "Alert not found"
  }
}
```

### Company blocked

```json
{
  "error": {
    "code": "COMPANY_BLOCKED",
    "message": "Company is blocked"
  }
}
```

### Status outside the valid values

When the `status` sent is not one of the three accepted values, body validation fails before processing and returns `VALIDATION_ERROR` (HTTP 422):

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid enum value. Expected 'notfound' | 'account_suspended' | 'other', received 'foo'"
  }
}
```

### Transition not allowed

When the `status` is valid but the transition is not allowed (deadline, expiration or status already final), the code is `ALERT_INVALID_STATUS` (HTTP 422). The message says which of the three cases happened:

```json
{
  "error": {
    "code": "ALERT_INVALID_STATUS",
    "message": "Alert has expired"
  }
}
```

```json
{
  "error": {
    "code": "ALERT_INVALID_STATUS",
    "message": "Response deadline has passed"
  }
}
```

```json
{
  "error": {
    "code": "ALERT_INVALID_STATUS",
    "message": "Alert already has a definitive status"
  }
}
```

These three only happen for Ethoca alerts; Verifi RDR has no deadline rules (see [Rules and deadlines](https://doc.rapidchargeback.com/en/produtos/alerta/regras-e-prazos/)).

---

## Customers from the previous system

If you integrated with the previous version of the platform, the old endpoint is still available as an alias:

```
POST https://api.rapidchargeback.com/chargeback-alert/update/status
```

This alias accepts the body in the old format `{ "alert_id": "...", "status": "..." }` and both Basic Auth and the `clientid`/`clientkey` headers. As in the previous system, **`alert_id` is the alert ID at the provider** (the same `alert_id` you receive in the `legacy` webhook format and use in `POST /chargeback-alert/get`); Rapid's UUID is also accepted. The response keeps the old format `{ "success": true, "message": "...", "status": "..." }` and adds `data` with the object of the canonical endpoint. Errors follow the new envelope (`422 VALIDATION_ERROR` / `ALERT_INVALID_STATUS`, `404 ALERT_NOT_FOUND`).

**Recommendation:** migrate to `PATCH /chargeback-alert/alerts/:id/status`. The alias will be removed in the future, once there are no more calls to it.