Webhooks de marketplace: por que nunca confio no que chega
O desenho que trata todo evento recebido como aviso, nunca como verdade, e o que fazer quando o payload não identifica de qual conta ele veio.
A primeira vez que abri um endereço público para receber webhooks de marketplace, dormi mal. Endereço público significa que qualquer pessoa na internet pode mandar um JSON para lá dizendo que existe um pedido novo. Se o meu sistema acreditasse nisso, alguém poderia criar pedido, baixar estoque e sujar meu financeiro sem nunca ter comprado nada.
O desenho do WAHub resolve isso de um jeito que parece óbvio depois de explicado: o evento recebido não é verdade. É aviso.
Vou detalhar o caminho completo do evento, o que é registrado, o que é enfileirado e onde entra a consulta autenticada que decide tudo. Se a importação em si ainda não está clara, leia antes importação de pedidos de marketplace no ERP.
Webhooks de marketplace avisam, o hub confere
Quando um evento chega, o hub registra o payload, resolve a empresa pelo identificador do seller e enfileira o evento. Nenhum efeito de pedido é aplicado antes da consulta autenticada, feita de servidor para servidor, diretamente ao canal.
A diferença é enorme. Um atacante pode conseguir que o hub gaste uma consulta ao canal. Ele não consegue fazer o hub criar pedido, baixar estoque ou lançar conta a receber com base no que ele mandou. A decisão vem sempre da resposta autenticada.
Os dois endereços públicos e o que cada um faz
Existe o webhook público por canal e existe o feed público por token. São coisas diferentes, com riscos diferentes, e vale não confundir uma com a outra na hora de configurar.
| Endereço | Para que serve | Cuidado principal |
|---|---|---|
| Webhook por canal | Receber aviso de evento do marketplace | Nunca aplicar efeito sem reconsultar o canal |
| Feed por token | Publicar o catálogo para comparadores | O token é o segredo; quem tem o link vê o catálogo |
O feed merece um texto próprio, e ele existe: feed XML para comparadores de preço. Aqui basta guardar que o token do feed não deve circular em grupo de WhatsApp nem em planilha compartilhada, coisa que eu já vi acontecer.
O problema de saber de quem é o evento
Quando existe mais de uma conta do mesmo canal e o evento não identifica o seller, o hub não escolhe uma empresa por suposição. Ele deixa o polling autenticado cobrir aquele evento. É mais lento e é certo.
Imagine a alternativa: um pedido da empresa A importado dentro da empresa B, com baixa de estoque no depósito errado e conta a receber no financeiro errado. Corrigir isso depois é bem pior do que esperar o próximo ciclo de consulta. Por isso o identificador externo do seller merece tanto cuidado no cadastro de contas e credenciais.
Duplicidade é regra, não exceção
Canais reenviam evento. Reenviam quando não recebem resposta rápida, quando o status muda de novo, às vezes sem motivo aparente. Já vi o mesmo pedido chegar quatro vezes em dois minutos.
- O evento é registrado e enfileirado, sem efeito imediato
- A fila deduplica antes de processar
- A importação é idempotente e não cria pedido repetido
- O polling cobre o que o evento não entregou
- O espelho guarda o payload bruto para conferência posterior
O que colocar no ar com cuidado
- Publique o endereço só com HTTPSEndereço público sem transporte seguro é um convite. Isso vale para o webhook e para o feed.
- Trate o token do feed como senhaGuarde onde você guardaria credencial, não onde guarda link de planilha.
- Confirme o identificador do sellerÉ o que permite resolver a empresa certa quando o evento traz essa informação.
- Monitore o volume de eventosPico sem venda correspondente merece uma olhada nos registros antes de virar problema.
A lentidão que vale a pena
Confesso que reclamei desse desenho no começo. Achava que reconsultar o canal a cada aviso era desperdício. Mudei de ideia no dia em que recebi um evento de pedido que não existia, provavelmente de um teste de terceiro apontado para o endereço errado. O hub consultou, o canal disse que não havia pedido, e nada aconteceu.
Segurança de integração é isso: escolher o caminho um pouco mais lento que não deixa dado inventado virar registro. Se você quer entender como esse evento vira trabalho de verdade, siga para fila de sincronização e política de tentativas e depois para gestão e permissões no ERP.