Como conectar Webhooks padrão ao Shopify Flow
Conecte Webhooks padrão (OpenAI, Supabase) ao Shopify Flow, com verificação HMAC para acionar fluxos apenas com eventos confiáveis.
O Standard Webhooks é uma especificação aberta para a assinatura de webhooks, utilizada pela OpenAI, pelo Supabase Auth Hooks e por uma lista cada vez maior de serviços. Uma configuração pré-definida abrange todos eles. O “Workflow Webhooks” transforma essa chamada em um gatilho “Shopify Flow”, para que sua loja possa reagir a ela: marcar um cliente, adicionar uma nota ao pedido, enviar um e-mail interno, atualizar um metacampo - tudo o que o Shopify Flow pode fazer.
Este guia define todo o fluxo - o Standard Webhooks envia, o Workflow Webhooks recebe e verifica, e o Shopify Flow executa - com a assinatura HMAC do Standard Webhooks verificada em cada solicitação, de modo que somente o Standard Webhooks possa iniciar seu fluxo de trabalho.
O que o senhor pode construir
- Receba um webhook da OpenAI - um trabalho em lote concluído ou uma resposta finalizada - e faça com que o Shopify Flow execute uma ação com base no resultado em sua loja.
- Reaja a um hook de autenticação do Supabase, de modo que um cadastro em seu próprio aplicativo associe o cliente correspondente no Shopify.
- Receba notificações de qualquer serviço que siga a especificação do standardwebhooks.com sem precisar configurar uma assinatura personalizada.
Eventos típicos a serem enviados: qualquer evento definido pelo serviço de envio.
Essa mesma configuração pré-definida também verifica os webhooks da OpenAI e do Supabase Auth Hooks.
Antes de começar
- Workflow Webhooks instalado na sua loja Shopify.
- Shopify Flow instalado, que está disponível gratuitamente na App Store do Shopify.
- Uma conta no Standard Webhooks com permissão para criar webhooks.
Etapa 1 - Crie o webhook em Workflow Webhooks
- Acesse Workflow Webhooks -> Webhooks -> Criar webhook e atribua a ele um nome que você reconheça no Shopify Flow, como
Standard Webhooks events. - Na seção “Autenticação”, selecione HMAC.
- Em “Provedor de assinatura”, selecione “Webhooks padrão”. O aplicativo preenche automaticamente o cabeçalho, o algoritmo, o payload assinado e a janela de repetição para você - não há mais nada a configurar.
- Deixe o campo “segredo” em branco por enquanto e clique em “Salvar”. Copie a URL da webhook exibida na página.
Consulte Autenticação para conhecer os outros modos de autenticação e Mapeamento de payload e variáveis de fluxo para escolher quais campos serão enviados para Shopify Flow.
Etapa 2 - Adicione o endpoint em “Webhooks padrão”
Adicione a URL como ponto final no serviço de envio e, em seguida, copie o segredo de assinatura exibido (que começa com whsec_).
Como localizar seu segredo de assinatura do Standard Webhook
O segredo de assinatura que começa com whsec_. Cole-o na íntegra; se ele for exibido como v1,whsec_... (Supabase), omita o “v1,” inicial.
A própria documentação do Standard Webhooks sobre assinaturas de webhooks, disponível em, contém o texto exato e as capturas de tela específicas para a sua conta.
Cole essa chave secreta no campo “Secret” do webhook em Workflow Webhooks e salve. A partir desse momento, todas as entregas do Standard Webhooks serão verificadas antes de chegarem ao Shopify Flow.
O que isso verifica
| O que | Valor |
|---|---|
| Cabeçalho de assinatura | webhook-signature |
| Onde fica a assinatura | O valor do cabeçalho, após o prefixo v1, |
| O que foi assinado | {header:webhook-id}.{timestamp}.{body} |
| Assinatura | HMAC-SHA256, codificado em base64 |
| Data e hora | O cabeçalho webhook-timestamp, em segundos do Unix |
| Proteção contra reprodução | As solicitações cujo carimbo de data e hora assinado esteja a mais de 5 minutos do momento atual são rejeitadas |
| O segredo | Decodificado em Base64 antes do uso. O whsec_ inicial é removido antes da decodificação. Cole exatamente como o remetente o apresenta |
Na payload assinada, {body} corresponde ao corpo bruto da solicitação, byte por byte; {timestamp} corresponde ao carimbo de data/hora mencionado acima; e {header:webhook-id} corresponde ao cabeçalho da solicitação webhook-id.
Uma solicitação que não atenda a qualquer um desses requisitos é rejeitada com o código de erro 401, é registrada em Histórico e solução de problemas e nunca inicia um fluxo de trabalho.
Etapa 3 - Criar o fluxo de trabalho Shopify Flow
- No “Shopify Flow”, crie um fluxo de trabalho e selecione o gatilho “Workflow Webhooks”.
- Clique em “Registrar eventos” e, em seguida, envie um evento de teste a partir dos Webhooks Padrão (ou utilize a opção “Enviar teste” em Workflow Webhooks) para que o Shopify Flow aprenda o formato dos seus dados.
- Cada webhook de que o senhor dispõe aciona o mesmo gatilho do Shopify Flow; portanto, adicione uma primeira condição com base no ID do webhook para restringir esse fluxo de trabalho apenas aos Webhooks Padrão. O ID é exibido na página do webhook.
- Adicione suas ações - marque um cliente, adicione uma nota, envie um e-mail interno, atualize um metacampo.
Etapa 4 - Teste de ponta a ponta
Gatilho de evento real nos Webhooks Padrão. Em Workflow Webhooks -> Histórico, vocês deverão ver a invocação com o status “Sucesso”. Caso a assinatura esteja incorreta, será exibida uma entrada com status de falha e o motivo correspondente; além disso, Verificação de webhooks assinados explica como funciona o verificador de assinaturas, que mostra exatamente qual etapa falhou.
A assinatura não corresponde
Nesta ordem: o segredo (a causa mais comum - um espaço a mais ou uma chave do ambiente errado), se o remetente está utilizando o segredo de um endpoint diferente e se algo entre os Webhooks Padrão e o aplicativo reescreve o corpo da mensagem. As assinaturas abrangem os bytes brutos; portanto, um proxy que reformata o JSON as invalida. O verificador de assinaturas na página do webhook mostra o texto exato que foi assinado.
Recebo um erro 401 em todas as solicitações
Verifique se a autenticação do webhook está configurada como HMAC com o provedor “Standard Webhooks” selecionado, se o segredo está preenchido e se o “Standard Webhooks” está enviando a solicitação para a URL exatamente como o aplicativo a exibe, incluindo o código no final.
Não há nada no Histórico
A solicitação nunca foi recebida. Verifique novamente a URL no Standard Webhooks e consulte o próprio registro de entrega do Standard Webhooks para verificar a resposta recebida. Um código de erro 404 indica um webhook incorreto ou excluído; um código de erro 429 significa que você ultrapassou o limite de invocações do seu plano - consulte Planos e uso.
O fluxo de trabalho é executado para os eventos incorretos
Cada webhook da sua loja aciona o mesmo gatilho do Shopify Flow. Adicione uma condição com base no ID do webhook como a primeira etapa do fluxo de trabalho ou restrinja os eventos que você envia a partir dos Webhooks Padrão.
As solicitações falham com a mensagem “carimbo de data/hora fora da tolerância”
O Standard Webhooks assina um carimbo de data e hora, e o aplicativo rejeita qualquer evento com mais de 5 minutos. Normalmente, isso se deve a um problema de relógio no lado do remetente ou a uma entrega que o Standard Webhooks tentou novamente muito tempo depois, mantendo o carimbo de data e hora original. Novas tentativas decorrentes da mesma solicitação original não são permitidas; solicite ao Standard Webhooks que envie um novo evento.
Relacionado
- Verificação de webhooks assinados - todos os prestadores de serviços que verificamos e como descrever aqueles que não verificamos.
- Mapeamento de payload e variáveis de fluxo - extrair os campos corretos do payload e inseri-los no Shopify Flow.
- Proteção contra entregas duplicadas - o que ocorre quando os Webhooks Padrão tentam novamente uma entrega.
- Histórico e solução de problemas - o registro de todas as solicitações, com reprodução.