Como ligar os Webhooks padrão ao Shopify Flow

O Standard Webhooks é uma especificação aberta para a assinatura de webhooks, utilizada pela OpenAI, pelos Supabase Auth Hooks e por uma lista crescente de serviços. Uma predefinição abrange todos eles. O «Workflow Webhooks» transforma essa chamada num gatilho «Shopify Flow», para que a 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 processo - 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 pedido, de modo a que apenas o Standard Webhooks possa iniciar o seu fluxo de trabalho.

O que 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 as ações necessárias com base no resultado na sua loja.
• Reaja a um «hook» de autenticação do Supabase, para que um registo na sua própria aplicação associe o cliente correspondente no Shopify.
• Receba notificações de qualquer serviço que siga a especificação do standardwebhooks.com sem ter de configurar uma assinatura personalizada.

Eventos típicos a enviar: qualquer evento definido pelo serviço de envio.

A mesma predefinição verifica também os webhooks da OpenAI e os Supabase Auth Hooks.

Antes de começar

• Workflow Webhooks instalado na sua loja Shopify.
• Shopify Flow instalada, que está disponível gratuitamente na App Store da Shopify.
• Uma conta no Standard Webhooks com permissão para criar webhooks.

Passo 1 - Crie o webhook em Workflow Webhooks

1. Aceda a Workflow Webhooks -> Webhooks -> Criar webhook e atribua-lhe um nome que consiga reconhecer no Shopify Flow, como, por exemplo, Standard Webhooks events.
2. Na secção «Autenticação», selecione HMAC.
3. Na secção «Fornecedor de assinatura», selecione «Webhooks padrão». A aplicação preenche automaticamente o cabeçalho, o algoritmo, o payload assinado e a janela de repetição - não há mais nada a configurar.
4. Por enquanto, deixe o campo «segredo» em branco e clique em «Guardar». Copie o URL do webhook apresentado na página.

Consulte Autenticação para conhecer os outros modos de autenticação e Mapeamento da carga útil e variáveis de fluxo para saber como escolher quais os campos que são enviados para o Shopify Flow.

Passo 2 - Adicione o ponto de extremidade nos Webhooks Padrão

Adicione o URL como ponto final no serviço de envio e, em seguida, copie o segredo de assinatura que lhe é apresentado (começa por whsec_).

Como encontrar o seu segredo de assinatura dos Webhooks Padrão

O segredo de assinatura que começa por whsec_. Cole-o na íntegra; se for apresentado como v1,whsec_... (Supabase), omita o «v1,» inicial.

A própria documentação da Standard Webhooks sobre assinaturas de webhooks, disponível em, contém o texto exato e as capturas de ecrã relativas à sua conta.

Cole essa chave secreta no campo «Secret» do webhook em Workflow Webhooks e guarde. A partir desse momento, todas as entregas do Standard Webhooks serão verificadas antes de chegarem ao Shopify Flow.

O que isto verifica

O quê	Valor
Cabeçalho da assinatura	webhook-signature
Onde se encontra 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 Unix
Proteção contra a reprodução	Os pedidos cujo carimbo temporal assinado se situe a mais de 5 minutos do momento atual são rejeitados
O segredo	Decodificado em Base64 antes da utilização. O prefixo whsec_ é removido antes da decodificação. Cole-o exatamente como o remetente o apresenta

Na payload assinada, {body} corresponde ao corpo da solicitação em formato bruto, byte a byte; {timestamp} corresponde ao carimbo temporal acima; e {header:webhook-id} corresponde ao cabeçalho da solicitação webhook-id.

Um pedido que não cumpra qualquer um destes requisitos é rejeitado com o erro 401, é registado em Histórico e resolução de problemas e nunca dá início a um fluxo de trabalho.

Passo 3 - Criar o fluxo de trabalho Shopify Flow

1. No «Shopify Flow», crie um fluxo de trabalho e selecione o gatilho «Workflow Webhooks».
2. Clique em «Registar 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 a estrutura dos seus dados.
3. Cada webhook de que dispõe aciona o mesmo gatilho do Shopify Flow; por isso, adicione uma primeira condição com base no ID do webhook para limitar este fluxo de trabalho apenas aos Webhooks Padrão. O ID é apresentado na página do webhook.
4. Adicione as suas ações - identifique um cliente, adicione uma nota, envie um e-mail interno, atualize um metacampo.

Passo 4 - Teste-o de ponta a ponta

Gatilho para um evento real nos Webhooks Padrão. Em Workflow Webhooks -> Histórico, deverá ver a invocação com o estado «Sucesso». Se a assinatura estiver incorreta, será apresentada uma entrada com o estado «Falha» e o motivo correspondente; em Verificação de webhooks assinados, é explicada a ferramenta de verificação de assinaturas, que lhe mostra exatamente em que etapa ocorreu a falha.

Relacionado

• Verificação de webhooks assinados - todos os prestadores que verificamos e como descrever aqueles que não verificamos.
• Mapeamento da carga útil e variáveis de fluxo - extrair os campos corretos da payload e transferi-los para o Shopify Flow.
• Proteção contra entregas duplicadas - o que acontece quando os Webhooks Padrão tentam novamente uma entrega.
• Histórico e resolução de problemas - o registo de cada pedido, com reprodução.