Verificar integrações externas
Última atualização: 6 de julho de 2026
A loja de roupas online "Guarda-Roupa Aconchegante" configurou um Webhook (uma integração que envia um aviso a um programa externo sempre que o conteúdo muda) para avisar automaticamente o bot de avisos interno da empresa sempre que um novo produto é cadastrado. Só que um dia a pessoa responsável diz: "ultimamente os avisos de novos produtos não chegam". O primeiro passo é distinguir se o aviso realmente não saiu ou se saiu, mas o bot deixou passar.
Depois de criado uma vez, o Webhook funciona sozinho, então no dia a dia você não precisa se preocupar com ele. Mas o programa externo que recebe os avisos está fora do seu alcance e, mais cedo ou mais tarde, chega o dia em que ele não responde ou devolve um erro. Esta página aborda, por meio de receitas para cada situação, como verificar se o Webhook configurado está funcionando bem e como localizar as chamadas que falharam e reagir conforme a causa.
O que é um Webhook e como criá-lo, ativá-lo, desativá-lo e editá-lo é o que a página Webhook aborda. Aqui o foco é operar e verificar um Webhook que já foi criado.
O que o histórico de chamadas registra
Sempre que o Webhook envia uma requisição ao programa externo, cada uma dessas vezes fica registrada no histórico de chamadas. Cada registro contém o seguinte:
- Quando foi enviada e quanto tempo levou o processamento
- Que mudança motivou o envio (por exemplo, o cadastro de um produto)
- Para qual endereço foi enviada
- O código de resposta que o programa externo devolveu (o número de resultado que indica como a requisição foi tratada)
- Se aquela chamada foi bem-sucedida ou falhou
O histórico de chamadas tem duas camadas. Primeiro há uma lista que percorre as chamadas em ordem cronológica; ao abrir um item da lista, aparecem os detalhes daquela chamada. Nos detalhes, você vê exatamente a requisição que enviamos e a resposta que o programa externo devolveu.
Na lista de Webhook, ao clicar no nome, a tela de detalhes abre, e essa lista aparece na aba Chamadas de Webhook no topo. Os registros que o Bot de avisos de novos produtos da "Guarda-Roupa Aconchegante" enviou sempre que um produto foi cadastrado ficam assim:
A lista mostra de forma resumida apenas Webhook chamado em e Resultado da chamada; o restante das informações, como para qual endereço e por que a chamada foi enviada, só aparece ao clicar na linha para abrir os detalhes. Se a lista parecer desatualizada, você pode recarregá-la com Atualizar Chamadas no canto superior direito.
Sucesso e falha são definidos pelo código de resposta. Se o código de resposta estiver na faixa normal (geralmente na casa dos 200 e 300), a chamada é registrada como sucesso; qualquer outro número é registrado como falha. Se o programa externo não responder nada, ou se a resposta devolvida for grande demais, aquela chamada também fica registrada como falha.
Verificar se os avisos estão saindo
Para confirmar se a pessoa responsável tem razão, primeiro veja qual porcentagem das chamadas que este Webhook enviou até agora foi bem-sucedida. A taxa de sucesso das chamadas aparece diretamente na lista de Webhook.
- Nas configurações do Space da loja de roupas, abra a tela de Webhook.
- Na lista, verifique a coluna Chamadas bem-sucedidas (%) na linha do
Bot de avisos de novos produtos.
Por exemplo, ela aparece como "66,67%". Se for 100%, todas as chamadas enviadas até agora tiveram sucesso e, nesse caso, quem deixou passar foi o bot. Se for menor que 100%, significa que o próprio aviso já ficou preso ao sair em algum momento, então a próxima seção mostra como encontrar essa causa.
Se não houver nenhuma chamada enviada até agora, não é que o aviso falhou, mas que ele nunca chegou a ser enviado. Isso acontece quando o Webhook está desligado (INACTIVE) ou quando, nesse período, não houve nenhuma mudança que correspondesse à condição configurada. Nesse caso, verifique na página Webhook se ele está ligado e a que mudanças ele foi configurado para reagir.
Encontrar a causa de uma chamada com falha
Se você vir uma falha, abra aquela chamada para ver o que deu errado. Nos detalhes aparecem, juntas, a requisição que enviamos e a resposta que o programa externo devolveu.
- Na aba Chamadas de Webhook do
Bot de avisos de novos produtos, clique na linha cujo resultado é falha. A tela Detalhe da chamada de Webhook abre. - Em Pedido, verifique para qual endereço e com que conteúdo a requisição foi enviada.
- Em Resposta, verifique o código de resposta e o conteúdo que o programa externo devolveu.
O código de resposta e o conteúdo devolvido indicam a causa. Se o código de resposta estiver na faixa de falha, o programa externo recebeu a requisição, mas falhou ao processá-la; nesse caso, muitas vezes a causa está escrita no conteúdo devolvido. Se não houver resposta alguma, ou o endereço não for encontrado, é possível que o endereço de destino tenha mudado ou que o programa esteja fora do ar.
Se você quiser encaminhar esta chamada exatamente como está à pessoa responsável pelo programa externo, use Copiar cURL no canto superior direito para copiá-la em um formato que permite reproduzir a chamada.
A requisição enviada também inclui os cabeçalhos que enviamos junto. Entre eles, os que foram definidos como valor secreto (por exemplo, o valor de chave usado para acessar o programa externo) aparecem ocultos por asteriscos na tela. O valor original não é exposto, então você pode consultar os detalhes com tranquilidade.
Se este Webhook também usa o WriteBack, que preenche o conteúdo de volta com a resposta, você pode ver se cada uma dessas ações teve sucesso ou falhou na aba WriteBack Resultados desse mesmo detalhe. O significado de cada item é abordado na página Webhook.
Como reagir quando há uma falha
Antes de tudo, há uma coisa a saber. As chamadas que falharam não são reenviadas automaticamente. Um aviso que falhou uma vez apenas fica registrado no histórico; o Webhook não o reenvia por conta própria. Por isso, a reação se divide em dois caminhos: corrigir a causa para que os próximos avisos saiam normalmente e cuidar você mesmo daquele caso que já falhou e o bot deixou passar.
Conforme o que você viu nos detalhes, as causas a investigar e as reações são as seguintes:
| O que aparece nos detalhes | Causa a investigar | Reação |
|---|---|---|
| Código de resposta na faixa de falha e conteúdo de erro | O programa externo falhou ao processar a requisição | Encaminhe o conteúdo da resposta devolvida, tal como está, à pessoa responsável pelo programa externo para que ela corrija do lado dela |
| Não há resposta ou o endereço não é encontrado | O endereço de destino mudou ou o programa está fora do ar | Verifique se o endereço está correto e, se tiver mudado, edite o Webhook |
| Nenhuma chamada fica registrada | O Webhook está desligado (INACTIVE) | Ligue o Webhook novamente |
| Fica registrada como falha e a resposta devolvida é muito grande | O conteúdo que o programa externo devolve é grande demais | Ajuste o programa externo para reduzir o conteúdo que ele devolve |
Como corrigir o endereço ou ligar o Webhook novamente é o que a página Webhook aborda.
Mesmo depois de corrigir a causa, os avisos que falharam nesse meio-tempo não são enviados de novo sozinhos. A qual cadastro de produto cada chamada com falha correspondeu pode ser verificado no conteúdo enviado, nos detalhes daquela chamada; portanto, para esses produtos, avise diretamente a pessoa responsável pelo bot, para cobrir o processamento que ficou faltando.