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

# Webhook cash_out

> Notificações do ciclo de vida de um SPEI cash-out

## Quando dispara

O webhook do tipo `cash_out` recebe os eventos do ciclo de vida de uma transferência criada via `POST /api/spei/cash-out`:

| `event`                         | `status`     | Significado                                                         |
| ------------------------------- | ------------ | ------------------------------------------------------------------- |
| `transaction.cash_out.settled`  | `LIQUIDATED` | A transferência foi liquidada na rede SPEI                          |
| `transaction.cash_out.rejected` | `REJECTED`   | A rede SPEI rejeitou a transferência — o saldo debitado é devolvido |
| `transaction.cash_out.pending`  | `PENDING`    | Atualização intermediária de processamento                          |

<Info>
  A **devolução** de um cash-out já liquidado (`transaction.cash_out.returned`) — quando o banco da contraparte devolve a transferência — é entregue no webhook do tipo [`refund_out`](/pt-br/guides/webhooks/refund-out), não no `cash_out`.
</Info>

## Payload

```json theme={"system"}
{
  "event": "transaction.cash_out.settled",
  "transactionId": "56789",
  "amount": 50000,
  "currency": "MXN",
  "status": "LIQUIDATED",
  "destinationClabe": "012180001234567890",
  "sourceClabe": null,
  "reference": "9876543",
  "voucher": "CEP20260513D4E5F6",
  "occurredAt": "2026-05-13T12:00:42.000Z"
}
```

Em `status: REJECTED`, os campos de comprovante (`reference`, `voucher`) podem vir `null` — a rede SPEI nunca confirmou a transação.

## Headers

| Header               | Valor                                  |
| -------------------- | -------------------------------------- |
| `x-event-id`         | UUID único do evento (use para dedupe) |
| `X-NTXPay-Signature` | `sha256=<hmac>` do corpo bruto         |

## Comportamento

* **At-least-once**: você pode receber o mesmo evento mais de uma vez. Deduplique por `x-event-id`.
* **Falha após sucesso**: não acontece. Uma transação não muda de `LIQUIDATED` para `REJECTED`.
* **Devolução**: se a contraparte devolver após a liquidação, você recebe `transaction.cash_out.returned` no webhook `refund_out`, com o mesmo `transactionId`.

## Resposta Esperada

`200 OK` em até 10 segundos.

## Processamento

```typescript theme={"system"}
const event = JSON.parse(rawBody.toString());
if (event.event === 'transaction.cash_out.settled') {
  await markPayoutSettled(event.transactionId);
} else if (event.event === 'transaction.cash_out.rejected') {
  await markPayoutFailed(event.transactionId); // saldo devolvido automaticamente
}
```

Para o handler completo com validação HMAC e dedupe em Node.js, Python, Java e Go, veja [Implementação](/pt-br/guides/webhooks/implementation).