Evento enviado por nos ao seu endpoint

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.

postWebhookevento

Headers

X-Webhook-Signaturestring

DEPRECATED, desligamento em 2026-11-09 — chaves criadas a partir de 2026-08-08 nao a recebem. Verifique a v2 (X-Lunium-Signature, HMAC de "timestamp.corpo", recuse > 5 min). Ate a data, integracoes existentes continuam recebendo esta assinatura v1 (HMAC do corpo bruto) normalmente.

X-Lunium-Signaturestring

Assinatura v2: t=<unix>,v1=<HMAC-SHA256 de "<t>.<corpo bruto>">. Prefira esta: como o timestamp entra no HMAC, voce pode recusar entregas antigas e uma entrega capturada nao pode ser reenviada contra voce depois. Tolerancia recomendada: 5 minutos.

X-Lunium-Eventstring

Nome do evento, para rotear sem abrir o corpo.

X-Lunium-Event-Idstring

Igual ao event_id do corpo.

X-Lunium-Delivery-Idstring

Identifica esta TENTATIVA (muda a cada retry). Cite no suporte.

X-Lunium-Attemptinteger

Numero da tentativa. >1 significa que voce ja pode ter recebido este evento.

X-Lunium-Timestampinteger

Unix time do envio; o mesmo t da v2.

Payload

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_idstring

Identidade ESTAVEL do evento — a mesma em toda retentativa. Guarde e ignore repetido: e o que garante que voce nao credita duas vezes.

created_atstring date-time required
dataobject required

Mesmo formato do endpoint de status da operacao correspondente.

Example payload

{
  "event_id": "evt_9c3f21a70b5e4d8812ff0a63"
}

Response

Recebido. Qualquer 2xx encerra a entrega.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.