Webhooks de Escrituração

Visão Geral

Os webhooks de escrituração permitem que você receba notificações em tempo real sobre mudanças de status e eventos importantes relacionados ao processo de emissão de Notas Comerciais. Quando um evento ocorre, a QI Tech envia automaticamente um payload HTTP POST para a URL configurada em seu sistema.

Configuração de Webhooks

Para receber webhooks, você precisa configurar uma URL de endpoint em seu sistema. Consulte a documentação de configuração de webhooks para mais detalhes sobre como cadastrar e gerenciar suas URLs de webhook.

Autenticação e Segurança

Todos os webhooks enviados pela QI Tech incluem um header SIGNATURE com um JWT assinado em HS256 com a Signature Key compartilhada com o parceiro. O corpo da requisição não é assinado diretamente: ele entra no token pelo claim payload_md5. Esta assinatura deve ser validada em seu sistema para garantir a autenticidade e integridade dos dados recebidos. Para o passo a passo da validação, consulte a documentação de autenticação de webhooks.

Eventos Disponíveis

Gestão de Emissores

Cadastro Emissor Aprovado

Enviado quando o cadastro de um emissor é aprovado pelo compliance.

Event Type: issuer_management.issuer_status_change

Payload:

{
  "event_type": "issuer_management.issuer_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "approved"
  }
}

Cadastro Emissor Reprovado

Enviado quando o cadastro de um emissor é reprovado pelo compliance.

Event Type: issuer_management.issuer_status_change

Payload:

{
  "event_type": "issuer_management.issuer_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "reproved"
  }
}

Auto-assinatura do Emissor — Mudança de Status

Enviado quando o envelope do termo de adesão é aberto e quando esse envelope é resolvido. O envelope é aberto durante a própria solicitação da habilitação, que já responde em pending_signature — para quem fez a chamada, este webhook confirma o que a resposta trouxe; para os demais consumidores do tenant, é o aviso de que o termo está disponível para assinatura. A habilitação é solicitada pelo integrador em POST .../auto_signature. Consulte o fluxo da auto-assinatura para o significado de cada status.

O evento é disparado em três momentos: pending_signature, enabled e reproved. A criação da auto-assinatura (pending_term_generation) e o cancelamento (canceled) não geram webhook — a criação é a resposta da própria solicitação, e o cancelamento é observado pela consulta da auto-assinatura.

Event Type: issuer_management.auto_signature_status_change

Payload:

{
  "event_type": "issuer_management.auto_signature_status_change",
  "event_datetime": "2026-02-10T09:16:03Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34",
    "status": "pending_signature"
  }
}

Campo	Tipo	Descrição
`issuer_key`	string	Chave única do emissor.
`issuer_auto_signature_key`	string	Chave única da auto-assinatura.
`status`	string	Status atual. No webhook, sempre `pending_signature`, `enabled` ou `reproved`.

Como tratar cada status recebido:

Status recebido	O que fazer
`pending_signature`	Consultar os links de assinatura e direcionar cada assinante do emissor ao seu próprio link.
`enabled`	O emissor está habilitado: as emissões seguintes são assinadas automaticamente.
`reproved`	O envelope do termo foi recusado, cancelado ou expirou. As emissões seguem pelo fluxo de assinatura manual até que uma nova habilitação seja criada.

Gestão de Contas de Liquidação

Abertura de Conta de Liquidação Rejeitada

Enviado quando o BaaS rejeita a abertura da conta de liquidação do emissor — por exemplo, por bloqueio no Bacen Protege+. A conta não é aberta, e a integralização do emissor fica impedida até que uma nova solicitação seja aprovada.

Não há evento correspondente de aprovação: a abertura bem-sucedida é observada pela consulta da conta de liquidação.

Event Type: liquidation_account.account_request_status_change

Payload:

{
  "event_type": "liquidation_account.account_request_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "account_request_key": "7e1c53d6-d372-4020-be6b-ed94248d7ae9",
    "status": "rejected",
    "rejection_reason": "Rejeitado devido ao Bacen Protege+",
    "account_info": {
      "account_branch": "0001",
      "account_number": "1234567",
      "account_digit": "3"
    }
  }
}

O campo account_info é opcional e só é enviado quando o BaaS informa os dados da conta recusada. O rejection_reason é repassado como recebido do BaaS.

Gestão de Investidores

Cadastro Investidor Aprovado

Enviado quando o cadastro de um investidor é aprovado pelo compliance.

Event Type: investor_management.investor_status_change

Payload:

{
  "event_type": "investor_management.investor_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "investor_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "approved"
  }
}

Cadastro Investidor Reprovado

Enviado quando o cadastro de um investidor é reprovado pelo compliance.

Event Type: investor_management.investor_status_change

Payload:

{
  "event_type": "investor_management.investor_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "investor_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "reproved"
  }
}

Gestão de Operações

Operação Aprovada

Enviado quando uma operação é aprovada pelo compliance e está pronta para ser enviada para assinatura.