1. Cadastre o endpoint
productIds vazio significa “todos os produtos”. Preenchido, o webhook só dispara para os produtos listados — é assim que se separa um ERP que só cuida de uma linha de produtos.
O segredo de assinatura volta mascarado (
signatureSecretMasked), e a máscara vale só para esta rota: GET /v1/webhook devolve o mesmo segredo inteiro, em texto puro, para qualquer token da empresa. Não trate o mascaramento como proteção. Some a isso o fato de que o segredo ainda não assina as entregas — leia Verificação e segurança antes de construir qualquer validação em cima dele.2. Dispare um teste
httpStatus é o que o seu servidor respondeu. O payload que chega é um evento completo com scope: "test" e ids de teste:
3. Investigue o que falhou
status: "error" com retries: 1 significa que a primeira tentativa falhou e a entrega está na fila de retentativa. GET /v1/webhook-deliveries/{deliveryId} traz o corpo enviado e a resposta recebida — é onde você descobre que o seu servidor devolveu 500 numa data inválida.
Para forçar um reenvio depois de corrigir o bug do seu lado:
4. Segure o volume
Em pico de lançamento,transaction_created pode chegar às centenas por minuto. A supressão descarta parte das entregas de um evento, numa janela fixa.
suppressCount precisa ser menor que interval, e interval no mínimo 2. Omitir o event reprova:
5. Confira as chaves e o time
active: false e a data em invalidatedAt — serve de auditoria. O segredo nunca volta por esta rota: ele só existe na tela de criação, no painel.
6. Confira o cadastro da empresa
Antes de um lançamento, vale conferir se a empresa estáactive — e pegar o próprio companyId, que nenhuma outra rota pede porque ele sai sempre do token.
status: "active" com isBlocked: false é a única combinação que vende. logoUrl é uma URL temporária assinada — baixe o arquivo, não guarde o link.
Mudou de sede? O endereço que sai em documento fiscal e o que a verificação de cadastro confere é este:
data: URL, e substitui o anterior:
image/png, image/jpeg, image/jpg e image/webp. Uma URL comum no lugar do data: URL é recusada na validação, com os formatos esperados na própria mensagem:
logo: null remove o logo atual e description: null apaga a descrição — omitir o campo, ao contrário, não mexe nele. A logoUrl que volta é assinada e temporária, como a de GET /v1/company: serve para conferir o envio, não para colar num site.
Os documentos de verificação já enviados saem em URLs temporárias do mesmo tipo:
null não é erro: significa que aquele documento ainda não foi enviado. Quatro null numa empresa que não consegue sacar é exatamente o diagnóstico da próxima seção.
O envio é a mesma rota com PUT, e cada arquivo também vai em base64 — aqui application/pdf entra na lista de formatos, com teto de 5 MB por arquivo:
A resposta traz os quatro depois da gravação, então dá para conferir o que ainda falta sem uma segunda chamada. Os documentos que ficaram de fora do corpo continuam como estavam, e reenviar um substitui o anterior. É este envio que resolve o
needsCompanyDocuments: true da próxima seção.
7. Descubra por que o saque não sai
Saque recusado quase nunca é problema de saldo: é a subconta no provedor de pagamento, que ainda não terminou de ser aprovada. Esta leitura nunca cria nem avança nada — pode chamar à vontade.
Numa empresa que não opera por subconta a resposta é toda neutra, e é assim que deve ser:
Todas as operações do domínio
Webhooks
Cadastrar, atualizar, testar e excluir endpoints.
Entregas
Histórico, detalhe de cada tentativa e reenvio.
Supressões
Regras de descarte por evento e janela.
Chaves e equipe
Chaves de API ativas e revogadas, membros e convites.
Empresa e subconta
Cadastro, endereço, marca, documentos e a situação que libera saque.
Integrações
Aplicativos externos, canais de comunidade e entrega automática.