Histórico e solução de problemas
Todas as solicitações que chegam a um webhook são registradas - sejam elas aceitas ou rejeitadas. O histórico é o primeiro lugar a ser consultado quando algo não ocorreu.
Leitura de uma invocação
Abra o “Histórico” e clique em uma entrada. Você terá acesso à data e hora, ao status, ao remetente, à duração, à payload, aos cabeçalhos da solicitação (ocultos), à string de consulta e, em caso de falhas, ao erro e a todas as tentativas de repetição.
| Status | Significado |
|---|---|
| Em espera | Aceito e colocado na fila, ainda não entregue a Shopify Flow |
| Sucesso | Shopify Flow aceitou o gatilho |
| Falha | A entrega falhou definitivamente - a página de detalhes explica o motivo |
A coluna “Invoked by” indica de onde veio uma chamada: User (um sistema externo), Flow (uma ação do Shopify Flow que aciona o webhook), Test (o botão “Testar”) ou CURL.
Rejeições e o que cada uma delas significa
Uma solicitação rejeitada nunca chega ao Shopify Flow. O corpo da resposta contém um código de status de rejeição (code) legível por máquina:
| Código | HTTP | O que deu errado | Corrigir |
|---|---|---|---|
webhook_not_found |
404 | Código curto desconhecido | Verifique a URL; o webhook pode ter sido excluído |
webhook_disabled |
400 | O webhook está desativado | Ative-o na página de webhooks |
unauthorized |
401 | Token ausente ou incorreto | Verifique o token e o nome do cabeçalho |
missing_signature |
401 | Modo HMAC, sem cabeçalho de assinatura | Envie o cabeçalho de assinatura que sua predefinição espera |
invalid_signature |
401 | A assinatura não correspondeu | Confirme o segredo de assinatura e verifique se o corpo da mensagem não sofreu alterações durante a transmissão |
auth_not_configured |
401 | O modo de autenticação está definido, mas nenhum token foi salvo | Salve um token no webhook |
invalid_json |
400 | O corpo da mensagem não está no formato JSON válido | Envie um JSON válido ou defina o Content-Type que o corpo da mensagem realmente possui (dados de formulário e XML também são lidos) |
invalid_body |
400 | Não foi possível ler um formulário ou o corpo XML, ou o corpo é o valor literal null |
Envie um objeto JSON ou um corpo de mensagem que corresponda ao seu Content-Type |
mapping_field_missing |
400 | Um campo mapeado está ausente da payload | Envie o campo ou remova-o do mapeamento |
unexpected_fields |
400 | O corpo possui campos que não estão mapeados | Mapeie-os, remova-os ou ative a opção “Permitir corpo de solicitação personalizado” |
ip_not_allowed |
403 | O endereço do chamador não consta na lista de endereços IP permitidos do webhook | Consulte Listas de endereços IP permitidos |
invalid_proxy_signature |
401 | O endereço do proxy do aplicativo foi acessado diretamente, em vez de por meio do domínio da sua loja | Utilize a URL do webhook exatamente como ela aparece no aplicativo - consulte CORS, a URL do proxy do aplicativo e as chamadas do navegador |
payload_too_large |
413 | Payload do Shopify Flow superior a 50 KB | Envie menos dados ou desative as opções de solicitação de dados |
quota_exceeded |
400 | Limite do plano atingido | Consulte Planos e uso |
Inspecionador de Solicitações em Tempo Real
Enquanto você tiver um webhook aberto no editor, o inspetor exibe as solicitações que chegam em tempo real - incluindo as rejeitadas, com o motivo. Essa é, de longe, a maneira mais rápida de depurar um remetente: envie uma solicitação e observe-a ser recebida.
As duplicatas suprimidas também aparecem aqui, identificadas como tal - consulte Proteção contra entregas duplicadas.
Repetição
Qualquer invocação anterior pode ser reproduzida a partir de sua página de detalhes. A reprodução reenvia a mesma payload por meio do mesmo webhook.
Há duas coisas para as quais ele é muito bom:
- Criação de um fluxo de trabalho no Shopify Flow. Registre eventos no gatilho Webhook e, em seguida, reproduza um evento real Execute essa chamada para que o Shopify Flow aprenda os nomes reais dos seus campos.
- Recuperação após uma falha no fluxo de trabalho. Corrija o fluxo de trabalho e, em seguida, repita os eventos que foram executados embora isso estivesse errado.
As repetições são identificadas como tal no histórico e não são contabilizadas no seu plano.
Situações comuns
As chamadas chegam, mas o fluxo de trabalho não é executado. Quase sempre, o problema está na condição do ID do Webhook. Um fluxo de trabalho acionado por Webhook recebe eventos de todos os webhooks de que você é proprietário; portanto, ele precisa de uma condição que corresponda ao ID específico do webhook - consulte Crie seu primeiro webhook.
O fluxo de trabalho é executado duas vezes. Ou dois fluxos de trabalho utilizam o gatilho Webhook sem condições distintas, ou o remetente está tentando novamente. O histórico indica qual das situações se aplica: duas entradas significam que chegaram duas solicitações. Ative a opção Proteção contra entregas duplicadas.
Não há absolutamente nada no Histórico. A solicitação nunca chegou até nós. Verifique o URL e o código curto, e se o remetente não está apresentando falhas de TLS ou DNS do lado dele.
O status permanece em “Pendente”. A entrega é repetida com intervalo de espera; uma falha permanente muda o status para “Falha” com o motivo correspondente. Caso permaneça pendente por um período excepcionalmente longo, verifique status.codecreationlabs.cloud.