Visão geral da entrada

Nos webhooks de entrada o fluxo se inverte: quem chama é um parceiro e quem responde é a loja. O gateway aprova um Pix, o emissor autoriza uma nota, o WhatsApp entrega uma mensagem, e cada um faz um POST para uma URL da Venddor. A plataforma confere que a chamada é legítima, atualiza o pedido, o pagamento ou a nota e responde.

Estas rotas não usam token de usuário. Elas são públicas na internet e se protegem com o segredo de cada integração. Quem configura a integração (a equipe da loja) cola a URL no painel do parceiro e cadastra o segredo correspondente no painel da Venddor. Esta seção documenta o contrato para quem constrói ou depura um conector.

Onde fica a URL

A URL é sempre o endereço da loja mais o caminho da rota:

https://minhaloja.io.venddor.com.br/api/v1/webhooks/pagarme

A loja é identificada pelo domínio da chamada. Por isso a URL cadastrada no parceiro tem de usar o domínio da loja, não um endereço genérico. Duas exceções existem: a rota de nota fiscal com {tenantID} no caminho, que escolhe a loja pelo identificador, e o callback central do WhatsApp, que não pertence a uma loja e descobre o destino pelo número de telefone.

Autenticação de cada parceiro

A regra comum é falhar fechado: sem segredo cadastrado na loja a chamada é recusada, em vez de aceita sem conferir. Isso protege contra quem descobre a URL e finge ser o gateway.

Respostas e novas tentativas

Cada parceiro tem a sua política de tentativas, e a resposta da loja foi desenhada para ela:

• Pagar.me repete a notificação quando recebe status diferente de 2xx. Uma notificação repetida de um evento já processado recebe 200 e não altera o pedido de novo.
• Braspag e ClearSale: a loja responde 200 mesmo quando o processamento interno falha ({"status":"error_logged"}), para o parceiro não repetir sem fim. Falhas de autenticação continuam sendo 401 ou 403.
• Nota fiscal (FocusNFe): referência desconhecida devolve 404 de propósito, para que o emissor entregue de novo mais tarde.
• WhatsApp (Meta) exige confirmação rápida e repete por vários dias quando não recebe 2xx. A loja confirma com 200 mesmo se o processamento interno falhar.

Módulos

Cada rota depende do módulo do parceiro estar ativo na loja (Pix, Pagar.me, Braspag, FocusNFe, ClearSale, WhatsApp Commerce). Com o módulo desligado a resposta é 403 com {"error":"module_disabled","module":"<slug>"}, exceto a rota genérica de pagamentos, que responde 200 com {"message":"module disabled"} para o gateway não repetir.

Testar uma rota de entrada

Simule o parceiro com curl usando o segredo cadastrado. Para as rotas de HMAC, calcule a assinatura sobre o corpo exato:

BODY='{"type":"charge.paid","data":{"id":"ch_123","code":"ORDER_3f73310d-bfdd-4713-a664-305c08eda58b"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$PAGARME_SECRET_KEY" | sed 's/^.* //')

curl -i -X POST "$BASE_URL/api/v1/webhooks/pagarme" \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature: $SIG" \
  -d "$BODY"

Teste só em uma loja de homologação: a chamada altera de verdade o status do pedido citado.

Rotas de entrada

Outros parceiros (outros gateways, transportadoras e canais) têm rotas próprias que não fazem parte desta seção.

Erros comuns

• Cadastrar a URL do domínio errado. O parceiro chama um domínio que não é o da loja e recebe 404 ou age sobre outra loja.
• Assinar o JSON reformatado. Em rotas de HMAC, a assinatura vale para os bytes exatos do corpo.
• Esquecer de cadastrar o segredo na loja. O parceiro está configurado, mas a loja recusa tudo com 401, 403 ou 503.
• Módulo desligado. module_disabled aparece quando o módulo do parceiro não foi ativado na loja.
• Testar em produção. As rotas atuam sobre pedidos reais.

Veja também

• Webhooks de saída: visão geral
• Verificar a assinatura