Como conectar o Sanity ao Shopify Flow
O Sanity envia um Webhook com tecnologia GROQ sempre que um conteúdo que corresponda à sua consulta for criado, atualizado ou excluído. O Workflow Webhooks transforma essa chamada em um gatilho do 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 de trabalho - a Sanity envia, Workflow Webhooks recebe e verifica, Shopify Flow executa - com a assinatura HMAC da Sanity verificada em cada solicitação, de modo que somente a Sanity possa iniciar seu fluxo de trabalho.
O que o senhor pode construir
- Atualize um metacampo Shopify quando a entrada correspondente no CMS for alterada, para que a loja virtual permaneça sincronizada.
- Envie um e-mail à sua equipe de merchandising quando uma página de destino for publicada.
- Inicie um fluxo de trabalho de atualização do cache após o lançamento de um conteúdo.
Eventos típicos a serem enviados: um documento é publicado, um documento é atualizado, um documento é excluído.
Antes de começar
- Workflow Webhooks instalado na sua loja Shopify.
- Shopify Flow instalado, que pode ser baixado gratuitamente na App Store do Shopify.
- Uma conta no Sanity 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
Sanity events. - Na seção “Autenticação”, selecione HMAC.
- Em “Provedor de assinatura”, selecione “Sanity”. 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 saber como escolher quais campos serão enviados ao Shopify Flow.
Etapa 2 - Adicione o endpoint no Sanity
No Sanity, acesse API -> Webhooks, crie um webhook com tecnologia GROQ utilizando a URL que você copiou e defina o segredo.
Como localizar seu segredo de assinatura do Sanity
A configuração do Secret no webhook baseado no GROQ.
A própria documentação da Sanity sobre assinaturas de webhooks, disponível em, contém o texto exato e as capturas de tela referentes à sua conta.
Cole essa chave secreta no campo “Secret” do webhook em Workflow Webhooks e salve. A partir desse momento, todas as entregas do Sanity serão verificadas antes de chegarem ao Shopify Flow.
O que isso verifica
| O que | Valor |
|---|---|
| Cabeçalho de assinatura | sanity-webhook-signature |
| Onde fica a assinatura | No valor v1 desse cabeçalho, que contém pares key=value separados por vírgulas |
| O que foi assinado | {timestamp}.{body} |
| Assinatura | HMAC-SHA256, codificado em base64url |
| Data e hora | O valor t do cabeçalho da assinatura, em milissegundos do Unix |
| Proteção contra reprodução | Nenhuma - esse remetente não assina o carimbo de data e hora; portanto, todas as assinaturas válidas permanecem válidas |
| O segredo | Utilizado como texto simples. Cole-o exatamente como o remetente o apresenta |
Na payload assinada, {body} é o corpo da solicitação em formato bruto, byte por byte, e {timestamp} é o carimbo de data/hora mencionado acima.
Uma solicitação que não atenda a qualquer um desses critérios é rejeitada com o código 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 “Gravar eventos” e, em seguida, envie um evento de teste a partir do Sanity (ou utilize a opção “Enviar teste” no Workflow Webhooks) para que o Shopify Flow aprenda o formato dos seus dados.
- Cada webhook de que o senhor é proprietário aciona o mesmo gatilho do Shopify Flow; portanto, adicione uma primeira condição com base no ID do webhook para que esse fluxo de trabalho se limite apenas ao Sanity. 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 para um evento real no Sanity. Em Workflow Webhooks -> Histórico, o(a) senhor(a) deverá visualizar a invocação com o status “Sucesso”. Caso a assinatura esteja incorreta, será exibida uma entrada com status de falha, acompanhada do motivo; além disso, Verificação de webhooks assinados explica como funciona o verificador de assinaturas, que indica exatamente em qual etapa ocorreu a falha.
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 o Sanity 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 Sanity selecionado, se o segredo está preenchido e se o Sanity 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 Sanity e consulte o próprio registro de entrega do Sanity para ver a resposta recebida. Um erro do tipo 404 significa que o webhook está incorreto ou foi excluído; um erro do tipo 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 errados▾
Cada webhook da sua loja aciona o mesmo gatilho do Shopify Flow. Adicione uma condição com base no ID do webhook como primeira etapa do fluxo de trabalho ou restrinja os eventos que você envia do Sanity.
Relacionado
- Verificação de webhooks assinados - todos os prestadores que verificamos e como descrever aqueles que não verificamos.
- Mapeamento de payload e variáveis de fluxo - extrair os campos corretos da payload e inseri-los em Shopify Flow.
- Proteção contra entregas duplicadas - o que ocorre quando o Sanity tenta novamente uma entrega.
- Histórico e solução de problemas - o registro de todas as solicitações, com reprodução.