Webhook 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

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, não no cash_out.

Payload

{
  "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

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.

Guia

Sandbox

Webhooks

Autenticação

SPEI

Webhooks Config

Quando dispara

Payload

Headers

Comportamento

Resposta Esperada

Processamento

​Quando dispara

​Payload

​Headers

​Comportamento

​Resposta Esperada

​Processamento

Quando dispara

Payload

Headers

Comportamento

Resposta Esperada

Processamento