Verificar integrações externas

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 Log de chamadas, 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:

Na lista, cada linha mostra Chamado em, Resultado da chamada (o código de resposta), que mudança provocou esta chamada (Ação do evento), quanto tempo levou (Duração) e o ID da requisição que aponta aquela chamada. Para qual endereço a chamada foi enviada e o que foi trocado só aparece ao clicar na linha e abrir os detalhes. Com a coluna Resultado você também pode filtrar separadamente só as chamadas bem-sucedidas ou só as que falharam. Se a lista parecer desatualizada, você pode recarregá-la com Atualizar Logs, no canto superior direito.

Os registros não ficam guardados por muito tempo. O registro de uma chamada bem-sucedida desaparece depois de 1 hora, e o de uma chamada com falha, depois de 3 dias. As falhas ficam mais tempo porque examinar a causa mais tarde é algo que nasce das falhas. Por isso, "o aviso que saiu direito ontem" pode já não estar na lista, e isso não significa que o aviso não saiu. Se você precisa guardar o histórico de envios por muito tempo, deixe esse registro no programa que recebe os avisos.

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 chamadas bem-sucedidas aparece diretamente na lista de Webhook.

1. Nas configurações do Space da loja de roupas, abra a tela de Webhook.
2. 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.

1. Na aba Log de chamadas do Bot de avisos de novos produtos, clique na linha cujo resultado é falha. Os detalhes daquela chamada abrem.
2. Em Pedido, verifique para qual endereço e com que conteúdo a requisição foi enviada.
3. Na parte de cima, em Status, verifique o código de resposta e, em Resposta, o conteúdo que o programa externo devolveu. Em Recurso · Ação aparece também que mudança provocou esta chamada.

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. Para entregar o registro inteiro como arquivo, use Transferir .json.

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.

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:

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.

O que fazer a seguir

• Webhook: aborda o que é um Webhook e como criá-lo, ligá-lo, desligá-lo e editar o endereço e as condições.
• Webhook (Referência da API): aborda os endpoints usados para consultar o estado das chamadas e o histórico de envios a partir de um programa.