O webhook envia os dados de um evento da Hubla, como uma venda aprovada, uma assinatura cancelada ou um reembolso, automaticamente para a URL de outro sistema assim que ele acontece. Assim, você conecta a Hubla a ferramentas como CRMs, emissores de nota e automações, sem precisar conferir nada manualmente.
Como configurar um webhook
Como enviar seus dados: 1 aviso por venda
Cada regra tem um modo de envio, escolhido no campo Como enviar seus dados. A diferença aparece nas vendas com mais de um produto, como produto principal + order bump.
| Integração recomendada | Modo de compatibilidade | |
|---|---|---|
| Venda de 1 produto | 1 aviso | 1 aviso |
| Venda com order bump | 1 aviso por venda, com todos os produtos dentro | 2 avisos por produto (3 produtos = 6 avisos) |
Lista de produtos (products) | Todos os produtos da venda | Só o produto daquele aviso |
ID em products[].id | ID do produto | ID da oferta principal do produto |
| Campos de order bump | Presentes (hasOrderBump, isOrderBump, amountCents) | Ausentes |
| Valores | Sempre os da venda real | Avisos repetidos com o total da venda e avisos por produto com valores rateados |
products[].id muda, e quem somava vários avisos para chegar ao valor da venda deve parar, porque agora chega um aviso com o total correto. Veja o passo a passo técnico em Como enviar seus dados.Para descobrir o modo de uma regra, edite a regra e veja a opção marcada em Como enviar seus dados. Se o campo não aparecer, a regra está no modo de compatibilidade. No código, o cabeçalho x-hubla-delivery-mode chega como standard (integração recomendada) ou compatibility (modo de compatibilidade).
Para trocar, depois de revisar o código, edite a regra, marque Integração recomendada e salve. Na próxima venda, confira no Histórico se chegou um aviso por venda com todos os produtos. O modo de compatibilidade continua funcionando; se houver data para desligá-lo, a Hubla avisa com antecedência por e-mail.
Como o Combo aparece no webhook
Na venda de um Combo, o webhook envia um único produto: o próprio Combo, com o valor total da venda. Os produtos que fazem parte do Combo não aparecem separados no payload.
Teste a sua integração
Na aba Configurações, clique nos 3 pontinhos da regra em Ações e escolha Testar configuração.
A janela mostra os eventos que serão testados. Por padrão, a Hubla envia dados fictícios. Se quiser, preencha Nome, Email, Telefone e Id do Usuário com dados de teste.
Clique em Enviar eventos.
Acompanhe os eventos enviados
Na aba Histórico, você vê todos os envios, inclusive os de teste, e pode abrir cada um para conferir os dados enviados ou reenviar o evento.
Cada envio mostra o status que o sistema de destino respondeu. Veja o que cada um quer dizer:
Quais eventos existem
A lista completa, com o conteúdo de cada evento, está em Eventos de webhook.
Boas práticas
x-hubla-token em cada aviso recebido.x-hubla-idempotency para identificar repetições.Mais orientações em Proteja seu endpoint e Boas práticas.
Dúvidas frequentes
- Recebo vários eventos de fatura para a mesma venda. Por quê?
A regra está no modo de compatibilidade e a venda teve order bump. Nesse modo, cada produto gera dois avisos. Troque a regra para Integração recomendada para receber um aviso por venda (revise o código antes). - Troquei para a integração recomendada e meu sistema não encontra mais o produto. E agora?
Na integração recomendada,products[].idtraz o ID do produto, e não mais o ID da oferta principal. Ajuste a busca do produto no seu sistema. - O Combo chega com os produtos separados?
Não. O Combo chega como um único produto, com o valor total da venda.
Ficou alguma dúvida?
Fale com o nosso suporte e a gente te ajuda! 💚