---
title: "Evento enviado por nos ao seu endpoint"
method: POST
path: "evento"
---

# Evento enviado por nos ao seu endpoint

`POST evento` (webhook)

Configure `webhook_url` (https publica) em POST /keys ou PATCH /keys/me. Responda 2xx rapido e processe async: qualquer coisa fora de 2xx vira retry com backoff exponencial (12 tentativas, ~7h). Verifique SEMPRE a assinatura. Entregas que esgotam as tentativas ficam visiveis em GET /webhooks/deliveries e podem ser recuperadas com o retry.

## Headers

- `X-Webhook-Signature` string
- `X-Lunium-Signature` string
- `X-Lunium-Event` string
- `X-Lunium-Event-Id` string
- `X-Lunium-Delivery-Id` string
- `X-Lunium-Attempt` integer
- `X-Lunium-Timestamp` integer

## Payload

- EventoWebhook: Corpo enviado por nos ao seu endpoint. Trate eventos desconhecidos como no-op: a lista cresce sem aviso e ignorar o que nao conhece e o comportamento correto.
  - `event` 'cashin.paid' | 'cashin.delayed' | 'cashin.held' | 'cashin.settled' | 'cashin.settlement_failed' | 'cashin.expired' | 'cashin.refunded' | 'cashin.failed' | 'cashout.awaiting_deposit' | 'cashout.deposit_detected' | 'cashout.confirming' | 'cashout.processing' | 'cashout.under_review' | 'cashout.awaiting_refund_address' | 'cashout.refunding' | 'cashout.completed' | 'cashout.receipt_ready' | 'cashout.refunded' | 'cashout.expired' | 'cashout.failed' | 'payout.sent' | 'payout.failed' | 'payout.refunded' | 'webhook.test' | 'saldo.liberado' | 'saldo.congelado' | 'saldo.transferido' | 'wallet.deposit_credited' | 'wallet.payment_completed' | 'wallet.payment_failed' | 'wallet.withdrawal.completed' | 'wallet.withdrawal.failed', required: Ramifique por aqui. `cashin.settled` e o evento de creditar seu cliente. `cashout.confirming`: progresso do depósito enquanto a corretora junta confirmações. Emitido em 25%, 50% e 75%, só em redes que exigem espera real (≥120 confirmações), com `confirmations` e `confirmations_required` no payload. Existe porque entre `cashout.deposit_detected` e o fim da espera pode haver meia hora de silêncio. `cashin.held`: PIX pago, mas a entrega retida por política da chave (não é a retenção do provedor, que aparece como `status: delayed`); o `data` traz `liberar_em`. `cashin.delayed`: PIX pago, retido no provedor por 24h (`delay_until`). `cashout.awaiting_refund_address`: a ordem precisa devolver e não tem carteira de retorno (`state: AWAITING_REFUND_ADDRESS`, `refund_address_required: true`). Peça a carteira ao seu cliente e envie em POST /cash-outs/{cashout_id}/refund-address; a Lunium nunca devolve para a origem do depósito. Vale para a venda de cripto e, desde a 1.44.0, para a venda de DePix. O `data` é a ordem, no mesmo formato de GET /cash-outs/{cashout_id}. Carteira USDT: `wallet.deposit_credited` (data: deposit_id, amount_received, asset, network, balance_available, credited_at) · `wallet.payment_completed` (data: payment_id, brl_amount, cashout_id, usdt_debited) · `wallet.payment_failed` (data: payment_id, brl_amount, cashout_id, status, refunded — `refunded: true` = a reserva voltou ao saldo). No teste os mesmos eventos chegam com `sandbox: true`.
  - `event_id` string: Identidade ESTAVEL do evento — a mesma em toda retentativa. Guarde e ignore repetido: e o que garante que voce nao credita duas vezes.
  - `created_at` string, date-time, required
  - `data` object, required: Mesmo formato do endpoint de status da operacao correspondente.

## Acknowledgement `200`

Recebido. Qualquer 2xx encerra a entrega.

## Other responses

- `default`: Nao-2xx agenda nova tentativa.

---

[API](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil.md) · [All operations](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/llms.txt) · [OpenAPI document](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/revisions/0b5a340fa9dd?raw)