O que é webhook: como funciona e quando usar no e-commerce

Um pedido entra na loja virtual e o seu BI, a planilha do financeiro ou o sistema do parceiro só fica sabendo meia hora depois, quando a próxima consulta roda. Ou o contrário: a consulta roda a cada minuto, gasta o limite de chamadas da API e quase sempre volta vazia.

Se você já se perguntou o que é webhook e por que ele resolve esse problema, este artigo explica de um jeito prático: como ele funciona, a diferença para a consulta por API, como saber que o aviso é verdadeiro, o que fazer quando ele chega duas vezes e como não perder nenhum evento quando o seu servidor cai.

Em resumo: webhook é um aviso automático que um sistema envia para outro quando algo acontece, como um pedido criado ou uma nota autorizada. Em vez de o seu sistema perguntar de tempos em tempos se houve novidade (polling), o sistema de origem faz uma chamada HTTP para um endereço seu no momento do evento. Para usar com segurança, confira a assinatura, responda rápido e trate os avisos repetidos sem duplicar nada.

O que é webhook, em palavras simples

Pense na diferença entre ligar para a transportadora a cada hora perguntando se a carga saiu e receber uma mensagem quando ela sai. O webhook é a mensagem.

Tecnicamente, é uma requisição HTTP, quase sempre um POST com o corpo em JSON, que o sistema de origem envia para um endereço que você cadastrou, a URL do webhook. Esse corpo descreve o evento: o que aconteceu, quando e com qual registro. O seu sistema recebe, confere, responde que recebeu e faz o que tiver que fazer: atualizar o estoque, avisar o cliente, gerar um lançamento.

Três peças sempre aparecem:

• O evento: o fato que dispara o aviso, como pedido.criado.
• O endereço: a URL do seu sistema que recebe o aviso, sempre com https.
• O segredo: uma chave combinada entre os dois lados, usada para assinar e conferir cada aviso.

Webhook ou API: a diferença entre avisar e perguntar

Webhook e API não são concorrentes. A API é a porta pela qual você pede e envia dados; o webhook é a campainha que avisa que vale a pena abrir a porta.

Consulta periódica (polling)

No polling, o seu sistema chama a API de tempos em tempos e pergunta se há pedido novo. É simples de construir, mas tem dois custos. Se a consulta for espaçada, a informação chega atrasada. Se for frequente, você gasta chamadas à toa e pode bater no limite de requisições, que quase toda API tem.

Webhook

No webhook, o sistema de origem avisa no momento do evento. A informação chega em segundos e só há tráfego quando existe novidade. Em troca, o seu lado precisa estar no ar para receber, conferir a origem e lidar com repetições.

Os dois juntos

As integrações mais confiáveis usam as duas coisas: o webhook para a velocidade e uma consulta periódica de conferência para pegar o que tiver escapado, como um aviso perdido durante uma queda. É assim que os pedidos das lojas virtuais entram no Ravion: o aviso do canal traz o pedido na hora, e uma conferência de hora em hora pega o que tiver ficado para trás. Se a integração for com o sistema de um fornecedor, veja também o que avaliar numa integração por API com o ERP do fornecedor.

Exemplos de webhook no e-commerce

Quase todo evento importante da operação pode virar um aviso:

• Pedido criado: dispara a separação, a reserva de estoque ou a mensagem de confirmação ao cliente.
• Pedido atualizado: mudou a situação, entrou o código de rastreio ou a nota foi ligada ao pedido.
• Nota fiscal autorizada: libera a etiqueta e a expedição, ou alimenta o sistema do contador.
• Nota fiscal cancelada: desfaz o que dependia dela.
• Pagamento aprovado ou estornado: atualiza o financeiro e serve de base para a conciliação de recebíveis.
• Estoque alterado: atualiza o saldo em outro canal ou no sistema de um parceiro.

O padrão é o mesmo em todos: um aviso curto e objetivo, e o seu sistema decide o que fazer com ele.

Assinatura: como saber que o aviso é verdadeiro

A URL do webhook é um endereço público. Qualquer pessoa que descobrir o endereço pode mandar um POST dizendo que um pedido foi pago. Por isso, webhook sério vem assinado.

O método mais usado é o HMAC com SHA-256. O sistema de origem calcula uma assinatura a partir do corpo do aviso e de um segredo que só os dois lados conhecem, e envia essa assinatura num cabeçalho. O seu sistema faz a mesma conta com o mesmo segredo e compara. Se bater, o aviso veio de quem tem o segredo e não foi alterado no caminho.

Alguns cuidados fazem diferença:

• Use o corpo cru. Calcule a assinatura sobre o texto exatamente como chegou, antes de converter o JSON. Reformatar o corpo muda os bytes, e a conta não bate.
• Confira o carimbo de tempo. Muitas assinaturas incluem o horário do envio. Recusar avisos antigos impede que alguém capture um aviso verdadeiro e o reenvie depois.
• Compare em tempo constante. Funções de comparação segura evitam que um atacante descubra a assinatura medindo o tempo de resposta.
• Guarde o segredo fora do código. Em variável de ambiente ou num cofre de segredos, e troque o segredo se houver suspeita de vazamento.

Reenvio: o que acontece quando o seu sistema cai

O sistema de origem considera o aviso entregue quando recebe uma resposta de sucesso, um status HTTP da faixa 2xx. Se o seu servidor estiver fora do ar, demorar demais ou devolver erro, o aviso não foi entregue, e a origem tenta de novo, normalmente com intervalos cada vez maiores.

Isso traz duas regras para quem recebe:

1. Responda rápido. Confira a assinatura, guarde o aviso numa fila e responda 2xx. O processamento pesado, como atualizar estoque, emitir documento ou chamar outro sistema, fica para depois. Quem processa tudo antes de responder corre o risco de estourar o tempo limite e receber o mesmo aviso de novo.
2. Não dependa só do aviso. Se o seu sistema ficar fora por muito tempo, a origem pode desistir das tentativas ou desligar o webhook. A consulta periódica de conferência é a rede de segurança.

Idempotência: como não processar o mesmo aviso duas vezes

Reenvio significa que o mesmo aviso pode chegar mais de uma vez: o seu sistema processou, a resposta se perdeu na rede e a origem tentou de novo. Se cada aviso criar um pedido, você terá pedido duplicado, estoque baixado duas vezes e cliente cobrado em dobro.

Idempotência é a propriedade de uma operação que pode ser repetida sem mudar o resultado. Na prática:

• Use o identificador da entrega. Cada aviso traz um id que se repete nas novas tentativas. Guarde os ids já processados e descarte os repetidos.
• Tenha uma chave única no banco de dados. O número do pedido de origem como chave única impede o segundo registro, mesmo que a checagem anterior falhe.
• Prefira definir a somar. "O saldo agora é 12" é seguro de repetir; "tire 1 do saldo" não é.
• Não confie na ordem. O aviso de pedido atualizado pode chegar antes do pedido criado. Na dúvida, busque o estado atual do registro pela API antes de agir.

Como o Ravion ajuda

A API e os webhooks do Ravion seguem essas práticas. A API REST cobre produtos, estoque, pedidos, notas fiscais e contatos e está documentada em OpenAPI 3.1 na página para desenvolvedores. As chaves são criadas em Sistema › Integrações › API e webhooks, com permissões por recurso, e vão no cabeçalho Authorization de cada chamada. O limite é de 300 requisições por minuto por chave; acima disso, a resposta é 429, com o tempo para tentar de novo no Retry-After.

Os webhooks avisam eventos como pedido.criado, pedido.atualizado, nota.autorizada e nota.cancelada, com um POST em JSON para o seu endereço https. Cada aviso traz o tipo do evento em X-Ravion-Evento, o id da entrega em X-Ravion-Entrega, que é o mesmo nas novas tentativas, e a assinatura HMAC-SHA256 com carimbo de tempo em X-Ravion-Assinatura. Se a entrega falhar, o Ravion tenta de novo em 1, 5 e 30 minutos e em 2, 6 e 12 horas; depois de 20 falhas seguidas, o webhook é desligado e pode ser ligado de novo na tela.

Para quem trabalha com distribuidora que usa o WinThor (TOTVS), a integração com ERP passa pelo Automati-Hub, parceiro de integração: o estoque das filiais chega a cada 5 minutos e as vendas vão ao WinThor numa fila que mostra o motivo de cada recusa, com reenvio só do que falta, sem duplicar. Como esse parceiro funciona está em o que é o Automati-Hub. Outros ERPs se conectam pela API e pelos webhooks, como projeto sob medida. API, webhooks e integração com ERP fazem parte do plano Enterprise.

Perguntas frequentes

Webhook é a mesma coisa que API?

Não. A API é o conjunto de rotas para consultar e enviar dados, chamadas quando o seu sistema quer. O webhook é o aviso que o outro sistema manda por conta própria quando um evento acontece. Na maioria das integrações, o webhook avisa e a API busca os detalhes.

O que acontece se o meu servidor estiver fora do ar?

O aviso não é confirmado e o sistema de origem tenta reenviar, em geral com intervalos crescentes. Se as falhas continuarem, ele pode desistir ou desligar o webhook. Por isso vale manter uma consulta periódica que confere o que pode ter escapado.

Como testar um webhook?

Comece com um endereço de teste que mostre as requisições recebidas, confira o formato do corpo e dos cabeçalhos e só depois aponte para o seu sistema. Teste também os casos difíceis: assinatura inválida, aviso repetido e aviso fora de ordem.

O webhook pode trazer dados pessoais?

Pode, quando o evento envolve clientes. Peça só os dados de que precisa, guarde pelo tempo necessário e proteja o endereço com https e assinatura. A Lei Geral de Proteção de Dados exige finalidade definida e medidas de segurança para qualquer tratamento de dados pessoais.

Preciso de um programador para usar webhooks?

Para receber, sim: alguém precisa construir o endereço que confere a assinatura, guarda o aviso e trata as repetições. Por isso, na hora de comparar sistemas, vale incluir API e webhooks documentados entre os critérios para escolher um ERP para e-commerce.

Conclusão

Webhook é o jeito de um sistema avisar o outro na hora em que algo acontece, sem consultas a cada minuto. Para funcionar bem, ele pede três cuidados: conferir a assinatura de cada aviso, responder rápido e processar depois, e tratar as repetições pelo id da entrega. Com uma consulta periódica de conferência por trás, nenhum pedido fica para trás.

Se a sua operação precisa conectar outros sistemas ao ERP, fale com um especialista ou veja os planos.