Workflow WebhooksWorkflow Webhooks

Como conectar o Stripe ao Shopify Flow

A Stripe é uma plataforma de pagamentos. Ela envia um Webhook para cada pagamento, reembolso, contestação, alteração de assinatura e evento de faturamento em sua conta. 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 - o Stripe envia, Workflow Webhooks recebe e verifica, Shopify Flow executa - com a assinatura HMAC do Stripe verificada em cada solicitação, de modo que somente o Stripe possa iniciar seu fluxo de trabalho.

O que o senhor pode construir

  • Marque um cliente do Shopify que tenha efetuado o pagamento por meio de um checkout do Stripe ou de um link de pagamento, para que seus segmentos permaneçam sincronizados.
  • Adicione uma nota ao pedido e alerte sua equipe assim que uma contestação for aberta.
  • Envie um e-mail à equipe quando um pagamento de assinatura falhar, para que alguém possa entrar em contato antes que o cliente cancele a assinatura.

Eventos típicos a serem enviados: payment_intent.succeeded, charge.refunded, charge.dispute.created, customer.subscription.deleted, invoice.payment_failed.

Antes de começar

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

Etapa 1 - Crie o webhook em Workflow Webhooks

  1. Acesse Workflow Webhooks -> Webhooks -> Criar webhook e atribua a ele um nome que você reconheça no Shopify Flow, como Stripe events.
  2. Na seção “Autenticação”, selecione HMAC.
  3. Em “Provedor de assinatura”, selecione Stripe. 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.
  4. 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 ao Shopify Flow.

A webhook com autenticação HMAC e o Stripe como provedor de assinatura, mostrando o campo “segredo de assinatura”, o que essa verificação avalia e as etapas para conectar o Stripe
Um remetente assinado, neste caso o Stripe: escolha o provedor, cole seu segredo de assinatura e o editor mostrará o que está marcado e como conectá-lo.

Etapa 2 - Adicione o endpoint no Stripe

No Painel do Stripe, acesse Desenvolvedores -> Webhooks, adicione um endpoint com a URL que você copiou e selecione os eventos que deseja enviar.

Como localizar seu segredo de assinatura do Stripe

Segredo de assinatura do webhook (whsec_...) no Painel do Stripe -> Desenvolvedores -> Webhooks.

A própria documentação do Stripe sobre assinaturas de webhooks contém o texto exato e as capturas de tela específicas para a sua conta.

Cole esse segredo no campo “Secret” do webhook em Workflow Webhooks e salve. A partir desse momento, todas as entregas do Stripe serão verificadas antes de chegarem ao Shopify Flow.

O que isso verifica

O que Valor
Cabeçalho de assinatura Stripe-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 hexadecimal
Data e hora O valor de t do cabeçalho da assinatura, expresso 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 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 a 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 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

  1. No “Shopify Flow”, crie um fluxo de trabalho e selecione o gatilho “Workflow Webhooks”.
  2. Clique em “Gravar eventos” e, em seguida, envie um evento de teste pelo Stripe (ou utilize a opção “Enviar teste” no Workflow Webhooks) para que o Shopify Flow aprenda o formato dos seus dados.
  3. 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 que esse fluxo de trabalho se limite exclusivamente ao Stripe. O ID é exibido na página do webhook.
  4. Adicione suas ações - marque um cliente, adicione uma nota, envie um e-mail interno, atualize um metacampo.
Shopify Flow
Em Shopify Flow, selecione “Selecionar um gatilho”, acesse Workflow Webhooks e escolha “Gatilho de Webhook”.
Condição do Shopify Flow: o ID do webhook é igual ao ID de um webhook
O primeiro passo de todo fluxo de trabalho: uma condição baseada no ID do webhook, para que o fluxo de trabalho seja executado apenas para esse webhook.
O fluxo de trabalho finalizado: Gatilho de webhook, uma condição baseada no ID do webhook e, em seguida, o envio de um e-mail interno no ramo “Verdadeiro”
O fluxo de trabalho final: gatilho, condição baseada no ID do webhook e, em seguida, sua ação no ramo “True”.

Etapa 4 - Teste de ponta a ponta

Gatilho para um evento real no Stripe. Em Workflow Webhooks -> Histórico, o(a) senhor(a) deverá ver a chamada com o status “Sucesso”. Caso a assinatura esteja incorreta, o(a) senhor(a) receberá, em vez disso, um registro de falha com o motivo; e Verificação de webhooks assinados explica como funciona o verificador de assinatura, que mostra exatamente em qual etapa ocorreu a falha.

Uma invocação foi aberta no History com seus cabeçalhos de solicitação, payload, status, duração e identificadores
Um evento registrado no History com o status “Sucesso” significa que Shopify Flow o aceitou.
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 Stripe 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 Stripe selecionado, se o segredo está preenchido e se o Stripe 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 Stripe e consulte o próprio registro de entrega do Stripe para ver a resposta recebida. Um erro do tipo 404 indica um webhook incorreto ou 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 primeiro passo do fluxo de trabalho ou restrinja os eventos que você envia do Stripe.

As solicitações falham com a mensagem “carimbo de data/hora fora da tolerância”▾

O Stripe assina um carimbo de data/hora, e o aplicativo rejeita qualquer evento com mais de 5 minutos. Normalmente, trata-se de um problema de sincronização de relógio no lado do remetente ou de uma transmissão que o Stripe tentou novamente muito mais tarde com o carimbo de data/hora original. As novas tentativas decorrentes da mesma solicitação original não podem ser aceitas; solicite ao Stripe que envie um novo evento.

Relacionado