Webhooks

Eventos assíncronos emitidos pela QI Tech durante o ciclo de vida da operação consignada militar. Todos seguem o protocolo unificado de Webhooks QI — 5 segundos pra resposta HTTP 200 com encoded_body assinado, 3 retries de 5 minutos em caso de falha.

Atenção!

Os webhooks da QI Tech não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos aos payloads a qualquer momento. Use desserialização permissiva.

Webhooks específicos do produto militar

Webhook	Quando dispara	Origem
military_payroll.balance.status_change	Resultado da consulta de margem (succeeded ou failed)	military-payroll-api
military_payroll.due_balance.status_change	Saldo devedor (usado em refin/port)	military-payroll-api
military_payroll.portability_contracts_report.status_change	Relatório de contratos pra portabilidade	military-payroll-api
credit_operation.collateral	Averbação ou desaverbação no Zetra	credit-operation-api

Webhooks comuns LaaS

Webhook	Status	Quando dispara
debt	waiting_signature	Operação criada, aguardando assinatura
debt	signature_finished	Assinatura concluída
debt	disbursed	Desembolso PIX/TED enviado
debt	canceled	Operação cancelada (ver cancel_reason_enumerator)
debt	canceled_permanently	Cancelamento definitivo
debt	settled	Operação liquidada (parcelas pagas)
reversal	pending_fund	Borrower pagou PIX QR de cancelamento — reversal iniciado
credit_transfer.received_portability	—	Portabilidade externa recebida (banco origem aceitou)
credit_transfer_status_change	—	Atualização do credit-transfer
installment.status_change	paid / overdue / etc	Mudança de status de parcela individual
laas.devolution.refund_receipt	refunded	Devolução de overpayment via PIX

Estrutura padrão do payload

Todos os webhooks LaaS seguem essa forma básica:

{
  "key": "<UUID da operação>",
  "data": { /* campos específicos do webhook */ },
  "status": "<status>",
  "webhook_type": "<tipo>",
  "event_datetime": "2026-06-01 14:30:00"
}

Exemplos

military_payroll.balance.status_change (sucesso)

{
  "webhook_type": "military_payroll.balance.status_change",
  "key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
  "status": "succeeded",
  "data": {
    "balance": 3500.00,
    "allowed_installment_numbers": [24, 36, 48, 60],
    "military_unit": "AMAN",
    "military_branch": "Sistema de Retribuição do Exterior",
    "category": "ATIVO",
    "name": "JOÃO DA SILVA",
    "document_number": "45507529710",
    "registration_code": "146254221",
    "birth_date": "1985-03-12",
    "grant_date": "2010-05-15"
  },
  "event_datetime": "2026-06-01 14:30:00"
}

credit_operation.collateral (averbação reservada)

{
  "webhook_type": "credit_operation.collateral",
  "key": "27a099df-4688-43cb-87fa-515b1cf343a5",
  "status": "success",
  "data": {
    "collateral_constituted": true,
    "enumerator": "successfully_reserved",
    "reservation_status": "reserved"
  },
  "event_datetime": "2026-06-01 15:00:00"
}

debt (cancelado)

{
  "webhook_type": "debt",
  "key": "27a099df-4688-43cb-87fa-515b1cf343a5",
  "status": "canceled",
  "data": {
    "cancel_reason": "Operação cancelada manualmente",
    "cancel_reason_enumerator": "manual"
  },
  "event_datetime": "2026-06-01 16:00:00"
}

reversal (cancelamento pós-desembolso)

{
  "webhook_type": "reversal",
  "credit_operation_key": "2893b8bd-8f4e-4e45-9325-fc7003beb869",
  "contract_number": "0000049333/TW",
  "reversal": {
    "status": "pending_fund",
    "amount": 2026.93,
    "amount_to_send": 2026.93,
    "is_total": true,
    "is_operation_canceled": true,
    "reversal_key": "eb0bbd1d-111d-4a61-bb65-c1f66a005ea2",
    "date": "2026-09-06"
  }
}

Cancel reasons (cancel_reason_enumerator)

Enumerador	Significado
manual	Cancelado via API ou portal
waiting_signature	Não assinou no prazo
not_collateral_constituted	Averbação falhou (consent_refused, consent_expired, etc.)
is_portability	Portabilidade falhou
pix_max_retry	Muitas falhas no desembolso PIX
lack_of_resource	Sem recurso pra desembolsar
kyc_not_accepted	KYC reprovado
agencia_conta_invalida	Erro em dados bancários do desembolso
invalid_account	Conta inválida
rejected_payment	Pagamento recusado pelo banco destino

→ Lista completa em Mapa de Status

Reenvio Manual

Webhooks podem ser consultados e reenviados via portal seguindo Reenvio de Webhooks.