A verificação da API de terceiros costuma começar pelo proxy — a rota de saída é configurada rápido e sem muitas perguntas. Depois chega o webhook do mesmo fornecedor — um callback avisando que o pedido foi pago, que o número recebeu um SMS ou que a tarefa terminou — e os dados simplesmente não chegam. Vamos entender por que o proxy não tem nada a ver com isso, de onde vem a falha e como estruturar o recebimento de callbacks para que ele não dependa do canal de saída.

O proxy muda a rota de saída, não abre a entrada

O servidor proxy fica entre o seu cliente e a API remota apenas no trecho de saída: você inicia a conexão, e ele substitui o endereço de retorno e o IP de onde a requisição é vista. Tudo o que acontece depois é a resposta a uma conexão que você mesmo já abriu. O webhook funciona ao contrário: quem inicia é o fornecedor, não você. Ele abre uma nova conexão para a URL que você registrou antes no painel ou nos parâmetros da requisição, e essa conexão não tem nenhuma relação com o canal pelo qual você acessou a API dele há pouco.

Daí a confusão típica: você trocou o canal de saída e achou que os callbacks agora seguiriam por outro caminho. Na prática, a rota da requisição de entrada é definida apenas por onde a URL do receptor aponta e por esse endereço estar visível de fora, e não por aquilo que carrega as suas requisições de saída.

Por que o callback não chega

Um webhook que some tem poucas causas, e todas estão do lado do receptor, não do remetente. A máquina está atrás do NAT de um roteador doméstico ou de escritório, sem porta redirecionada — vista de fora, o endereço dela simplesmente não existe. O endereço local de desenvolvimento não é resolvido a partir da internet. A URL registrada aponta para um host interno, visível só dentro da rede corporativa. O certificado TLS está vencido ou foi emitido para outro domínio, e o handshake é interrompido antes de o corpo da requisição ser enviado. O servidor responde com um código diferente de 2xx — a maioria dos fornecedores desiste de reenviar depois de algumas tentativas malsucedidas.

Há ainda uma causa à parte: a allowlist do próprio fornecedor. A infraestrutura mudou, o registro não foi atualizado, e as chamadas morrem em silêncio, sem nenhum erro na interface.

Como receber callbacks do jeito certo

O receptor de callbacks precisa ser um endereço publicamente acessível, com porta aberta e certificado TLS válido — um domínio ou IP que o fornecedor consiga alcançar diretamente, sem proxy nem túneis do seu lado. Esse requisito não se cruza com o canal que você usa nas requisições de saída para a mesma API.

A arquitetura correta de recebimento separa duas tarefas: confirmar o recebimento rapidamente e processar os dados com calma. Na entrada fica um handler leve, que salva o corpo bruto da requisição numa fila e responde 200 na hora, sem esperar pela lógica de negócio. O processamento acontece de forma assíncrona, a partir da fila, num processo separado. Isso protege contra timeouts do lado do fornecedor: se o processamento útil leva segundos e o limite de resposta é uma fração de segundo, o esquema síncrono mais cedo ou mais tarde começa a perder eventos a qualquer queda de desempenho.

Se não dá para ter um endereço público — ambiente fechado, bancada de testes, ambiente temporário sem domínio —, use polling no lugar do push: a maioria dessas APIs oferece um endpoint paralelo para consultar o status ou a lista de eventos. Consulte-o em intervalos programados. O atraso para receber o evento passa de segundos para o intervalo da consulta, mas a exigência de acessibilidade pública deixa de existir por completo.

Verificação da entrega

A verificação é feita com dois logs independentes, e não com um só. O primeiro é o registro de entregas no painel do fornecedor: nele aparecem as tentativas, os códigos de resposta e os tempos. O segundo é o log do seu próprio receptor: o fato de a requisição ter chegado fisicamente ao seu código, e não ter sido interceptada por um balanceador ou CDN que respondeu 200 por conta própria, sem repassar o corpo adiante. O status «entregue» na interface de terceiros, sem um registro correspondente na sua fila, é sinal de falha em algum ponto do meio do caminho, e não motivo para considerar a integração funcionando.

Vale conferir também a assinatura: se o webhook é assinado com uma chave HMAC e o segredo ficou desatualizado após uma rotação, o servidor rejeita em silêncio eventos válidos como se fossem falsos — vista de fora, a situação parece «não chega nada».

Onde o proxy ainda é necessário

Ele continua útil no trecho de saída dessa mesma conexão. Se você migrou para polling no lugar do push, cada consulta é uma requisição de saída para a API, e ela pode ser distribuída como qualquer outro tráfego para o servidor de terceiros: por geolocalização, por frequência, com rotação de endereço em caso de rate limit. Outro cenário é conferir o que a própria plataforma mostra a partir do país desejado: se o callback depende de uma lógica específica de geolocalização do fornecedor, é mais prático verificá-la a partir da região adequada, e não do endereço padrão de um data center.

Perguntas frequentes

Dá para receber webhooks por meio de um servidor proxy?

O fornecedor precisa alcançar o seu receptor diretamente, e o canal que você usa para as requisições de saída não participa dessa cadeia. Se for preciso esconder o endereço real do servidor, coloca-se um proxy reverso na frente dele — é outro papel, que não deve ser confundido com o proxy de saída para as requisições do cliente à API de terceiros.

Por que o painel do fornecedor diz «entregue», mas os dados não aparecem?

O status «entregue» significa que o provedor recebeu uma resposta 2xx do seu endereço — quem respondeu pode ter sido um balanceador, uma CDN ou outro serviço no mesmo domínio, sem repassar o corpo adiante para a fila. Compare o log do fornecedor com o log do seu próprio receptor, em vez de confiar apenas no status da interface de terceiros.

O que fazer se não dá para ter um endereço público?

Passe para o polling: consulte o endpoint de status em intervalos programados, em vez de esperar pela notificação push. O atraso para receber o evento aumenta, mas a exigência de acessibilidade pública da máquina deixa de existir por completo.

Para a parte de saída dessa conexão — consultar a API do fornecedor ou verificar a lógica a partir do país desejado —, serve um canal dedicado ou rotativo do catálogo de proxies. A configuração está no artigo rotação de IP por API, e as métricas do canal, no material como verificar a qualidade do proxy.