Como conectar o Square ao Shopify Flow
A Square envia um Webhook para pagamentos, pedidos, reembolsos, clientes e alterações no estoque em seus produtos de ponto de venda e online. O Workflow Webhooks transforma essa chamada em um Webhook 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 Square envia, Workflow Webhooks recebe e verifica, Shopify Flow executa - com a assinatura HMAC da Square verificada em cada solicitação, de modo que somente a Square possa iniciar seu fluxo de trabalho.
O que o(a) senhor(a) pode construir
- Marque um cliente do Shopify que tenha efetuado uma compra em sua loja física por meio do Square.
- Adicione uma observação ao registro do cliente quando for emitido um reembolso pelo Square, para que a equipe de suporte tenha uma visão completa da situação.
- Envie um e-mail à equipe quando o estoque no Square de um SKU compartilhado ficar abaixo de um limite mínimo.
Eventos típicos a serem enviados: payment.created, refund.updated, customer.created, inventory.count.updated.
Antes de começar
- Workflow Webhooks instalado na sua loja do Shopify.
- Shopify Flow instalado, que está disponível gratuitamente na App Store do Shopify.
- Uma conta no Square 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
Square events. - Na seção “Autenticação”, selecione HMAC.
- Em “Provedor de assinatura”, selecione “Square”. 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 do 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 no Square
No Painel do Desenvolvedor do Square, abra a seção “Webhooks” do seu aplicativo, adicione uma assinatura com a URL que você copiou e copie a chave de assinatura.
Como encontrar sua senha de assinatura do Square
A chave de assinatura da assinatura do webhook (Painel do Desenvolvedor do Square -> Webhooks).
A própria documentação da Square sobre assinaturas de webhooks 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 Square serão verificadas antes de chegarem ao Shopify Flow.
O que isso verifica
| O que | Valor |
|---|---|
| Cabeçalho de assinatura | x-square-hmacsha256-signature |
| Onde fica a assinatura | O valor completo do cabeçalho |
| O que foi assinado | {url}{body} |
| Assinatura | HMAC-SHA256, codificado em base64 |
| Data e hora | Não é utilizado por este remetente |
| 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 carga útil assinada, {body} é o corpo da solicitação em formato bruto, byte a byte, e {url} é a URL deste webhook.
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 pelo Square (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 restringir esse fluxo de trabalho exclusivamente ao Square. 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
Acionem um evento real no Square. 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 em qual etapa ocorreu a falha.
A assinatura não corresponde▾
Nesse pedido: 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 Square 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 Square selecionado, se o segredo está preenchido e se o Square 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 chegou. Verifique novamente a URL no Square e consulte o próprio registro de entrega do Square para ver 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 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 Square.
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 da payload e inseri-los no Shopify Flow.
- Proteção contra entregas duplicadas - o que acontece quando a Square tenta novamente efetuar uma entrega.
- Histórico e solução de problemas - o registro de todas as solicitações, com reprodução.