Webhooks

Eventos assíncronos emitidos pela QI Tech durante o ciclo de vida da operação consignada SIAPE. 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 SIAPE

Webhook	Quando dispara	Origem
federal_payroll.balance	Resultado da consulta de margem (succeeded ou failure)	federal-payroll-api
credit_operation.collateral	Averbação ou desaverbação no SIGEPE	credit-operation-api
credit_transfer.received_portability	Portabilidade externa recebida (banco origem aceitou)	credit-transfer-api
credit_transfer_status_change	Atualização do credit-transfer	credit-transfer-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
debt	canceled_permanently	Cancelamento definitivo
debt	settled	Operação liquidada
reversal	pending_fund	Borrower pagou PIX QR de cancelamento — reversal iniciado
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

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

Exemplos

federal_payroll.balance (sucesso)

{
  "webhook_type": "federal_payroll.balance",
  "key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
  "status": "succeeded",
  "data": {
    "balance_query": [
      {
        "available_balance": 3500.00,
        "authority_code": "17000",
        "registration_code": "1354387",
        "employment_relationship": "active",
        "consigned_credit": 1200.00,
        "consigned_card": 300.00
      }
    ]
  },
  "event_datetime": "2026-06-02 14:30:00"
}

credit_operation.collateral (pending_consent)

{
  "webhook_type": "credit_operation.collateral",
  "key": "27a099df-4688-43cb-87fa-515b1cf343a5",
  "status": "pending_consent",
  "data": {
    "collateral_constituted": false,
    "enumerator": "waiting_borrower_consent"
  },
  "event_datetime": "2026-06-02 15:00:00"
}

credit_operation.collateral (success)

{
  "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-02 15:30:00"
}

debt (disbursed)

{
  "webhook_type": "debt",
  "key": "27a099df-4688-43cb-87fa-515b1cf343a5",
  "status": "disbursed",
  "data": {
    "ted_receipt_list": [{
      "amount": 12500.00,
      "transaction_key": "...",
      "destination": { "name": "MARIA DOS SANTOS", "bank_ispb": "60746948" }
    }]
  },
  "event_datetime": "2026-06-02 16:00:00"
}

reversal (cancelamento pós-desembolso)

{
  "webhook_type": "reversal",
  "credit_operation_key": "2893b8bd-...",
  "contract_number": "0000049333/TW",
  "reversal": {
    "status": "pending_fund",
    "amount": 12500.00,
    "is_total": true,
    "is_operation_canceled": true,
    "reversal_key": "...",
    "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

→ Lista completa em Mapa de Status

Reenvio Manual

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