Webhooks e eventos

Um webhook é uma chamada HTTP que um sistema faz para outro no momento em que algo acontece, em vez de o outro ficar perguntando de tempos em tempos. A Venddor usa webhooks nos dois sentidos. Nos webhooks de saída, a plataforma faz um POST para uma URL sua quando um pedido é criado, um produto muda, um cliente se cadastra e assim por diante. Nos webhooks de entrada, um gateway de pagamento, uma transportadora, um emissor de nota fiscal ou o WhatsApp faz um POST para a loja avisando que um pagamento foi aprovado, uma nota foi autorizada ou chegou uma mensagem.

Esta seção explica os dois sentidos, lista todos os eventos com o corpo real de cada um, mostra como verificar a assinatura de cada chamada e documenta as rotas para cadastrar e acompanhar webhooks. Ela também cobre os modificadores de dados, o catálogo de transformações que a importação de produtos aplica a cada linha.

Como funciona

Webhooks de saída

1. Escolha os eventos

   Consulte o catálogo de eventos e decida quais interessam. Um ERP costuma assinar order.created e order.statusChanged. Um indexador de busca assina product.*.

2. Cadastre a URL

   Chame Cadastrar webhook (administrador) ou Webhooks do seller (lojista). A resposta traz o secret. Ele não será mostrado de novo.

3. Teste

   Use Enviar evento de teste para ver a sua URL receber uma chamada real, assinada, com event: "test".

4. Verifique a assinatura e responda 2xx

   Calcule o HMAC do corpo bruto e compare com o cabeçalho (Verificar a assinatura). Responda 200 logo e processe o evento em segundo plano.

5. Acompanhe

   Consulte o registro de entregas para ver status HTTP, tempo de resposta e erro de cada tentativa, e reenvie uma entrega que falhou.

Webhooks de entrada

Você (ou a equipe da loja) informa a URL da Venddor no painel do gateway. Quando o gateway tem algo a dizer, chama essa URL. A Venddor valida a autenticação, atualiza o pedido, o pagamento ou a nota fiscal e responde. As regras de cada parceiro estão em Visão geral da entrada.

Conceitos-chave

Quem recebe o quê (administrador e seller)

Existem dois tipos de assinante de saída.

Um seller (lojista) é um vendedor do marketplace que opera dentro da loja. Quando um pedido não pertence a nenhum seller (venda direta da loja), nenhum webhook de seller o recebe.

Módulo webhooks

As rotas de cadastro e o próprio envio dependem do módulo webhooks estar ativo na loja. Com o módulo desligado, as rotas respondem 403 com {"error":"module_disabled","module":"webhooks"} e nenhum evento é enviado.

O envelope e o evento

Todo envio tem o mesmo envelope JSON, com o corpo do evento dentro de payload:

{
  "event": "order.created",
  "payload": { "type": "order.created", "order_id": "..." },
  "timestamp": "2026-10-11T20:15:03Z",
  "webhook_id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11"
}

O nome do evento também vai no cabeçalho X-Venddor-Event. O catálogo completo de payload está em Eventos.

Entrega, ordem e idempotência

Cada evento vira uma chamada independente, disparada em paralelo. Dois eventos do mesmo pedido podem chegar fora de ordem, e um evento pode chegar mais de uma vez. Trate cada chamada como uma notícia de que algo mudou e, quando a ordem importar, consulte o estado atual do recurso pela API. Os detalhes e uma receita de deduplicação estão em Entrega, reenvios e idempotência.

Dinheiro, ids e datas

Nos corpos de evento, valores em dinheiro são inteiros em centavos (4990 = R$ 49,90). Os ids são UUID em string. As datas são RFC 3339. Os status de pedido que vêm em old_status e new_status são os nomes por extenso (pending, shipped), não as letras gravadas no pedido.

Modificadores de dados

Não são webhooks. São as transformações que a importação de produtos aplica a um campo de cada linha (aumentar preço em 10%, adicionar um prefixo ao nome). Ficam nesta seção porque o catálogo é publicado por uma rota de administração. Veja Modificadores de dados.

Endpoints

Erros comuns

• Verificar a assinatura sobre o JSON reformatado. O HMAC é calculado sobre os bytes exatos recebidos. Se o seu framework já converteu o corpo em objeto e você o serializa de novo, a assinatura nunca bate. Use o corpo bruto.
• Processar tudo antes de responder. O limite de resposta é de 30 segundos e qualquer 5xx ou timeout gera reenvio. Responda 200 primeiro e processe depois.
• Responder 4xx para "não quero esse evento". Respostas 4xx encerram a entrega sem novas tentativas. Se o seu receptor está momentaneamente indisponível, devolva 503, não 400.
• Supor ordem. order.statusChanged de "enviado" pode chegar antes do de "pago". Compare timestamp do evento ou consulte o pedido.
• Perder o secret. Ele só aparece na criação. As listagens mostram **** mais os 4 últimos caracteres. Não existe rota para trocar o segredo: remova o webhook e cadastre outro.
• URL interna. URLs que apontam para localhost, redes privadas, endereços de metadados de nuvem ou domínios .internal, .local e .localhost são recusadas. Para testar localmente use um túnel público (HTTPS).
• Esperar eventos customer.* ou cart.* em webhook de seller. O seller só assina order.* e product.*.

Próximos passos