Problemas com webhooks de pagamento
Neste guia, você encontra solucoes para os problemas mais comuns relacionados ao recebimento de vendas no Oráculo via webhooks. Use a pergunta que mais se parece com a sua situacao para ir direto a solucao.
”As vendas não estão aparecendo”
Você fez uma venda na plataforma de pagamento (Eduzz, Kiwify, Hotmart etc.), mas ela não aparece no Oráculo.
Verifique estas 4 coisas:
1. Webhook não configurado
A causa mais comum. O webhook precisa estar configurado na plataforma de pagamento para enviar notificações para o Oráculo.
- Acesse a plataforma de pagamento
- Va até a area de webhooks ou notificações
- Adicione a URL do webhook do Oráculo
- Veja o guia “Configurando webhooks de pagamento” para instrucoes detalhadas por plataforma
2. URL do webhook errada
Se a URL estiver digitada incorretamente, a plataforma envia para o endereço errado é o Oráculo nunca recebe.
- No Oráculo, va até o evento e copie a URL de webhook correta
- O padrao e:
https://api.oraculo.work/webhook/{expert_id}/{plataforma} - Compare com a URL configurada na plataforma de pagamento
- Corrija se necessário (atencao ao expert_id e ao nome da plataforma)
3. Secret ou token incorreto
Algumas plataformas (como Hotmart e Kiwify) usam um secret ou token para autenticar o webhook. Se estiver errado, o Oráculo rejeita a notificação por seguranca.
- Verifique o secret configurado no Oráculo (nas configurações do expert)
- Compare com o secret configurado na plataforma de pagamento
- Os dois devem ser identicos
4. Produto não cadastrado
Se o produto vendido não está cadastrado no evento do Oráculo, a venda pode não ser processada.
- No Oráculo, va até o evento
- Na aba de Produtos, verifique se o produto está cadastrado com o ID correto da plataforma
”Venda apareceu como órfã”
A venda apareceu no Oráculo, mas não está vinculada a nenhum lead. Aparece como “órfã”.
Por que acontece
O Oráculo vincula lead e venda pelo telefone ou email. Se o comprador usou um telefone ou email diferente na plataforma de pagamento do que usou ao se cadastrar como lead, o sistema não consegue fazer o match.
O que fazer
- Isso e normal e acontece com frequencia — pessoas usam dados diferentes em plataformas diferentes
- A venda foi registrada corretamente e aparece nos relatorios de vendas
- Para melhorar o match no futuro, incentive os leads a usarem o mesmo telefone no cadastro e na compra
Dica: Você pode tentar vincular a venda manualmente verificando o nome do comprador e procurando o lead correspondente.
”Venda duplicada”
A mesma venda aparece duas vezes no Oráculo.
Por que normalmente NAO acontece
O Oráculo tem protecao de idempotencia: se a plataforma enviar o mesmo webhook duas vezes (com o mesmo ID de transacao), o sistema ignora a segunda vez automaticamente.
Quando parece duplicada mas não e
Verifique se são realmente a mesma venda:
- Mesmo ID de transacao?
- Mesmo valor?
- Mesmo comprador?
Se forem transacoes diferentes (por exemplo, o comprador fez duas compras separadas), e comportamento normal — são duas vendas de verdade.
Se for realmente duplicada
Em casos raros, a plataforma pode enviar webhooks com IDs diferentes para a mesma venda. Nesse caso, entre em contato com o suporte da plataforma de pagamento.
”Como testar se o webhook está funcionando”
Você acabou de configurar o webhook e quer saber se está tudo certo.
Passo 1: Faca uma compra de teste
A maioria das plataformas de pagamento oferece modo de teste ou sandbox. Use essa função para simular uma compra.
Passo 2: Verifique no Oráculo
Apos a compra de teste:
- No Oráculo, va até Operação > Vendas
- A venda de teste deve aparecer na lista em poucos segundos
- Se aparecer, o webhook está funcionando
Passo 3: Verifique os logs (se não aparecer)
- No Oráculo, va até Configuração > Eventos > [seu evento] > Logs
- Webhooks recebidos (com sucesso ou erro) são registrados nos logs
- Se o webhook chegou com erro, o log mostra a mensagem de erro
- Se não chegou nenhum webhook, o problema está na configuração da plataforma de pagamento
Passo 4: Verifique na plataforma
A maioria das plataformas mostra o histórico de webhooks enviados, incluindo se a entrega foi bem-sucedida (código 200) ou se houve erro.
”Qual URL do webhook?”
A URL do webhook do Oráculo segue este padrao:
https://api.oraculo.work/webhook/{expert_id}/{plataforma}Onde:
- {expert_id} é o ID do expert no Oráculo
- {plataforma} é o nome da plataforma (eduzz, xgrow, hotmart, kiwify, monetizze, guru, perfectpay)
Para copiar a URL correta sem erro:
- No Oráculo, va até Configuração > Eventos
- Selecione o evento
- Na aba de webhooks, a URL aparece pronta para copiar
Screenshot: [Configuração do evento mostrando URL de webhook de pagamento pronta para copiar]
O Stripe usa uma rota diferente: https://api.oraculo.work/webhook/stripe. A configuração do Stripe e feita nas integrações do expert no Oráculo.
Perguntas frequentes
Quais plataformas de pagamento são suportadas?
Eduzz, Xgrow, Hotmart, Kiwify, Monetizze, Guru, PerfectPay e Stripe.
O webhook e em tempo real?
Sim. Quando a plataforma processa a venda, ela envia o webhook imediatamente. A venda aparece no Oráculo em segundos.
Posso receber webhooks de mais de uma plataforma?
Cada expert usa uma plataforma de pagamento. Se você tem experts diferentes com plataformas diferentes, cada um tera seu proprio webhook configurado.
O que acontece se o Oráculo estiver fora do ar?
A maioria das plataformas faz retentativas automaticas. Se o Oráculo não responder na primeira vez, a plataforma tenta de novo depois de alguns minutos.
Resumo rapido
| Problema | Causa provavel | O que fazer |
|---|---|---|
| Venda não aparece | Webhook não configurado ou URL errada | Configurar/corrigir webhook |
| Venda órfã | Telefone diferente entre lead e comprador | Normal — match por telefone |
| Venda duplicada | Raro, sistema tem protecao | Verificar se são vendas diferentes |
| Quer testar | — | Compra teste + verificar logs |
| Não sabe a URL | — | Copiar em Configuração > Eventos |