Endpoints de Webhook

Visão Geral

Os Endpoints de Webhook permitem que sua aplicação receba notificações em tempo real sempre que eventos relevantes ocorrem na plataforma — como pagamentos aprovados, cobranças expiradas ou assinaturas canceladas. Ao cadastrar um endpoint, a plataforma enviará um POST para a URL configurada com o payload do evento.

Header obrigatório

Todas as rotas de webhook-endpoints exigem o header account com o código da conta:

account: acc_abc123xyz

Formato de resposta padrão

{
  "mensagem": "Mensagem descritiva",
  "erro": false,
  "mensagenserro": [],
  "codigoretorno": 200,
  "id": "00000000-0000-0000-0000-000000000000",
  "data": { ... }
}

Eventos disponíveis

Ao criar ou atualizar um endpoint, informe no campo events os eventos que deseja monitorar. A coluna Payload indica o formato do envelope entregue — o campo webhook_version do payload carrega esse mesmo valor.

Os payloads detalhados nesta documentação são os do formato v1, cujo envelope é { type, id, webhook_version, data }. Os eventos marcados como v2 são entregues com um envelope diferente — { id, type, webhook_version, created_at, data } — e o campo webhook_version do próprio payload informa qual formato você recebeu. Use-o para rotear o processamento no seu endpoint.

Pedidos

Evento	Descrição	Payload
`order.paid`	Pedido totalmente pago	`v2`
`order.failed`	Pedido falhou e nenhuma cobrança foi concluída	`v1` e `v2`
`order.refunded`	Todas as cobranças do pedido foram estornadas	`v2`
`order.chargeback`	Pedido sofreu chargeback	`v2`
`order.challenged`	Pedido entrou em contestação pelo antifraude	`v1`
`order.unprocessed`	Pedido bloqueado antes do processamento	`v1`

Cobranças

Evento	Descrição	Payload
`charge.created`	Cobrança criada	`v2`
`charge.pending`	Cobrança aguardando pagamento	`v2`
`charge.paid`	Cobrança paga	`v2`
`charge.failed`	Cobrança falhou	`v2`
`charge.reproved`	Cobrança reprovada pelo emissor	`v2`
`charge.refunded`	Cobrança estornada por completo	`v2`
`charge.partial_refunded`	Parte do valor da cobrança foi estornada	`v2`
`charge.chargeback`	Cobrança sofreu chargeback	`v2`
`charge.expired`	Cobrança expirou sem pagamento	`v1`
`charge.canceled`	Cobrança cancelada	`v1`

Assinaturas

Evento	Descrição	Payload
`subscription.canceled`	Assinatura cancelada	`v1`
`subscription.delayed`	Assinatura em atraso	`v1`
`subscription.regularized`	Assinatura em atraso regularizada	`v1`

Faturas

Evento	Descrição	Payload
`invoice.created`	Fatura da assinatura criada	`v1`
`invoice.failed`	Cobrança da fatura falhou	`v1`

Cartões

Evento	Descrição	Payload
`card.created`	Cartão salvo na conta	`v1`
`card.updated`	Cartão atualizado	`v1`
`card.deleted`	Cartão removido	`v1`
`card.expired`	Cartão salvo expirou	`v1`
`card.token_pending`	Tokenização do cartão ficou pendente	`v1`
`card.token_created`	Token do cartão criado na adquirência	`v1`
`card.token_failed`	Tokenização do cartão falhou	`v1`

Nota fiscal

Evento	Descrição	Payload
`tax_invoice.issued`	Nota fiscal do pedido emitida e autorizada	`v1`

Recebedores

Evento	Descrição	Payload
`receiver.bank_data_ready`	Dados bancários do recebedor ficaram prontos	`v1`
`receiver.bank_data_failed`	Cadastro dos dados bancários falhou	`v1`
`receiver.kyc_pending`	KYC do recebedor ficou pendente	`v1`
`receiver.kyc_verified`	KYC do recebedor verificado	`v1`
`receiver.kyc_failed`	KYC do recebedor falhou	`v1`
`receiver.kyc_link_generated`	Link de validação de identidade gerado	`v1`
`receiver.kyc_validation_approved`	Validação de identidade aprovada	`v1`
`receiver.kyc_validation_rejected`	Validação de identidade rejeitada	`v1`

Conta

Evento	Descrição	Payload
`account.kyc_pending`	KYC da conta ficou pendente	`v1`
`account.kyc_verified`	KYC da conta verificado	`v1`
`account.kyc_failed`	KYC da conta falhou	`v1`

Saques

Evento	Descrição	Payload
`withdrawal.approved`	Saque aprovado	`v1`
`withdrawal.reproved`	Saque reprovado	`v1`
`withdrawal.awaiting_acquisition_balance`	Saque aguardando saldo na adquirência	`v1`

Apenas os eventos listados acima são entregues aos endpoints da conta. Outros valores podem ser aceitos no cadastro, mas nunca resultarão em uma notificação — não construa sua integração em cima deles.

Status do webhook

Valor	Descrição
`Ativo`	Endpoint ativo — recebe notificações
`Inativo`	Endpoint desativado — não recebe eventos

O payload enviado para o seu endpoint varia conforme o tipo de evento. Certifique-se de que sua URL retorne HTTP 2xx para confirmar o recebimento.

Remover um webhook é uma operação irreversível. Os logs de requisições anteriores são mantidos, mas o endpoint não receberá novos eventos.

Autenticação

Cobranças

Pedidos

Cartões

Assinaturas

Faturas

Links de Pagamento

Análise de Fraude

Webhooks

Endpoints de Webhook

Visão Geral

Header obrigatório

Formato de resposta padrão

Eventos disponíveis

Pedidos

Cobranças

Assinaturas

Faturas

Cartões

Nota fiscal

Recebedores

Conta

Saques

Status do webhook

​Visão Geral

​Header obrigatório

​Formato de resposta padrão

​Eventos disponíveis

​Pedidos

​Cobranças

​Assinaturas

​Faturas

​Cartões

​Nota fiscal

​Recebedores

​Conta

​Saques

​Status do webhook

Visão Geral

Header obrigatório

Formato de resposta padrão

Eventos disponíveis

Pedidos

Cobranças

Assinaturas

Faturas

Cartões

Nota fiscal

Recebedores

Conta

Saques

Status do webhook