create

Webhooks

A API de Webhooks permite que o seu sistema seja notificado de forma assíncrona sobre eventos que ocorrem na plataforma.

Quando usar

Criar configuração: Utilize para registrar um novo webhook para um tipo específico (account ou transaction).

Atualizar configuração: Caso já exista uma configuração ativa para o tipo desejado, utilize a rota de update (atualização) em vez de tentar criar uma nova.

Regras de Validação

Ao enviar o payload para a API, certifique-se de seguir as regras abaixo:

type (Obrigatório): Deve ser estritamente account ou transaction.

hosts (Obrigatório): Array contendo as URLs que receberão os eventos. Deve ter no mínimo 1 item.

hosts.*: Cada item do array deve ser uma URL válida e possuir no máximo 2048 caracteres.

events (Opcional): Array contendo os eventos específicos que deseja escutar. Se não enviado, todos os eventos disponíveis para o tipo serão despachados.

events.*: Quando enviado, os valores devem ser eventos obrigatórios e válidos de acordo com o catálogo do type escolhido.

Erros Comuns

400 Bad Request: Retornado quando já existe um webhook ativo para o tipo (type) informado.

422 Unprocessable Entity: Retornado quando há dados inválidos no payload (exemplo: type incorreto, evento inexistente ou URL mal formatada).

Catálogo de Eventos Válidos

Abaixo estão listados os eventos disponíveis para cada tipo de webhook, juntamente com suas descrições detalhadas.

Tipo: `account` (Eventos de Conta)

Estes eventos refletem o ciclo de vida (onboarding) de uma conta digital e atualizações em suas configurações de limites operacionais.

Evento	Descrição
`register`	Registrada: A intenção de abertura de conta foi recebida. A análise de dados e documentos (KYC/KYB) ainda não foi iniciada.
`validating`	Em Validação: A conta e os documentos enviados estão passando pelo processo de análise de compliance e prevenção a fraudes.
`validated`	Validada: Os dados/documentos foram aprovados na fase de compliance e a conta está pronta para a criação sistêmica.
`processing`	Em Processamento: A conta bancária está sendo efetivamente gerada e provisionada na infraestrutura (agência, conta, etc).
`rejected`	Rejeitada: A abertura foi reprovada por inconsistências reversíveis nos dados (ex: foto ilegível, documento vencido). Pode ser corrigida e reenviada.
`denied`	Negada: A abertura foi negada em definitivo pelo motor de risco ou compliance. Não é possível reenviar os dados para esta solicitação.
`approved`	Aprovada: A conta foi criada com sucesso, está ativa e pronta para uso e movimentações.
`fail`	Falha: Erro sistêmico ou falha de infraestrutura durante a criação da conta. Geralmente requer reprocessamento técnico.
`disabled`	Desativada: A conta foi encerrada ou inativada, seja por solicitação do usuário, inatividade ou decisão administrativa.
`blocked`	Bloqueada: A conta sofreu um bloqueio impedindo a movimentação de recursos.
`transactions_limit_update`	Atualização de Limites: Disparado quando ocorre alguma alteração (aprovação/rejeição) nos limites transacionais operacionais da conta.

Tipo: `transaction` (Eventos de Transação)

Estes eventos notificam movimentações e operações financeiras realizadas na conta.

Evento	Descrição
`ACCOUNT_CREATION`	Disparado quando ocorre a efetivação sistêmica de uma nova conta de pagamento associada.
`DEPOSIT_BOLETO`	Confirmação de entrada de recursos (Cash-in) via liquidação de boleto de depósito.
`DEPOSIT_DIRECT_DEBIT`	Entrada de recursos na conta via débito direto autorizado.
`DEPOSIT_INSTANT_PAYMENT`	Entrada de recursos via recebimento de uma transferência Pix.
`PAYMENT_BOLETO`	Saída de recursos (Cash-out) devido ao pagamento de um boleto bancário (título comum).
`PAYMENT_BOLETO_COBRANCA`	Entrada de recursos (Cash-in) referente ao pagamento de um boleto de cobrança gerado pela conta.
`PAYMENT_DIRECT_DEBIT`	Saída de recursos da conta via débito direto autorizado.
`PAYMENT_INSTANT_PAYMENT`	Saída de recursos devido ao envio de uma transferência Pix.
`WITHDRAW_BANK_TRANSFER`	Saída de recursos via transferência bancária externa (como TED ou TEF).
`WITHDRAW_BOLETO`	Movimentação de retirada/saída de recursos estruturada via formato de boleto.
`WITHDRAW_INSTANT_PAYMENT`	Saída de recursos via Pix (frequentemente associado a funcionalidades como Pix Saque/Troco).
`WITHDRAW_INSTANT_PAYMENT_RETURN`	Entrada/Estorno decorrente da devolução de um Pix que havia sido enviado anteriormente pela conta.
`WITHDRAW_UTILITIES`	Saída de recursos para o pagamento de contas de consumo (água, luz, telefone, impostos, etc).
`INTERNAL_PAYMENT`	Movimentação de recursos caracterizada por transferência interna (entre contas da mesma instituição/BaaS).
`INTERNAL_PAYMENT_UNLOCK`	Confirmação de desbloqueio e efetivação de um pagamento interno que estava retido (exemplo: em análise de fraude).
`INSTANT_PAYMENT_ALIAS`	Notificação sobre o ciclo de vida das chaves Pix (criação, portabilidade, reivindicação ou exclusão).
`MED`	Notificação relacionada ao Mecanismo Especial de Devolução do Pix (abertura de disputa, bloqueio cautelar ou resolução).

Forneça seu token bearer no cabeçalho

Authorization

ao fazer requisições para recursos protegidos.

Exemplo:

Authorization: Bearer ********************

application/json

Bodyapplication/json

Exemplo

{
  "data": {
    "type": "account",
    "hosts": [
      "https://meu-sistema.com/webhooks/accounts"
    ],
    "events": [
      "approved",
      "validated"
    ],
    "is_active": true
  }
}

Webhooks

Quando usar

Regras de Validação

Erros Comuns

Catálogo de Eventos Válidos

Tipo: `account` (Eventos de Conta)

Tipo: `transaction` (Eventos de Transação)

Requisição

Respostas

create

Webhooks#

Quando usar#

Regras de Validação#

Erros Comuns#

Catálogo de Eventos Válidos#

Tipo: account (Eventos de Conta)#

Tipo: transaction (Eventos de Transação)#

Requisição

Respostas

Webhooks

Quando usar

Regras de Validação

Erros Comuns

Catálogo de Eventos Válidos

Tipo: `account` (Eventos de Conta)

Tipo: `transaction` (Eventos de Transação)