Como conectar o Paddle ao Shopify Flow
A Paddle é uma plataforma de processamento de pagamentos para produtos digitais e assinaturas. Ela o notifica sobre transações, assinaturas, reembolsos e alterações relacionadas aos clientes. O Workflow Webhooks transforma essa notificação 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 permite fazer.
Este guia define todo o fluxo - o Paddle envia, Workflow Webhooks recebe e verifica, Shopify Flow executa - com a assinatura HMAC do Paddle verificada em cada solicitação, de modo que somente o Paddle possa iniciar seu fluxo de trabalho.
O que o senhor pode construir
- Marque um cliente do Shopify que também tenha uma assinatura do “Paddle”, para que ele veja os preços ou o conteúdo corretos.
- Envie um e-mail à sua equipe quando uma assinatura for cancelada e o cliente tiver pedidos recentes no Shopify.
- Registre o plano atual no registro do cliente como um metacampo.
Eventos típicos a serem enviados: transaction.completed, subscription.canceled, adjustment.created (reembolso), customer.updated.
Antes de começar
- Workflow Webhooks instalado na sua loja do Shopify.
- Shopify Flow instalado, que está disponível gratuitamente na App Store da Shopify.
- Uma conta no Paddle 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
Paddle events. - Na seção “Autenticação”, selecione HMAC.
- Em “Provedor de assinatura”, selecione “Paddle”. 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 ao Shopify Flow.
Etapa 2 - Adicione o endpoint no Paddle
No Paddle, abra Ferramentas do desenvolvedor -> Notificações, adicione um destino com a URL que você copiou e selecione os eventos. A chave secreta é exibida no destino.
Como descobrir seu segredo de assinatura do Paddle
A chave secreta do destino da notificação (Paddle -> Ferramentas do desenvolvedor -> Notificações).
A própria documentação do Paddle 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 Paddle serão verificadas antes de chegarem ao Shopify Flow.
O que isso verifica
| O que | Valor |
|---|---|
| Cabeçalho de assinatura | Paddle-Signature |
| Onde fica a assinatura | No valor h1 desse cabeçalho, que contém pares key=value separados por ponto-e-vírgula |
| O que foi assinado | {timestamp}:{body} |
| Assinatura | HMAC-SHA256, codificado em hexadecimal |
| Data e hora | O valor de ts 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 por byte, e {timestamp} é o carimbo de data/hora mencionado acima.
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 “Gravar eventos” e, em seguida, envie um evento de teste pelo Paddle (ou use 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 possui 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 Paddle. 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 Paddle. Em Workflow Webhooks -> Histórico, o(a) senhor(a) deverá ver a invocação com o status “Sucesso”. Caso a assinatura esteja incorreta, o(a) senhor(a) receberá, em vez disso, uma entrada com status de falha e o motivo correspondente; e Verificação de webhooks assinados explica o verificador de assinatura, que mostra 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 algum elemento entre o Paddle 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 Paddle selecionado, se o segredo está preenchido e se o Paddle 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 Paddle e consulte o próprio registro de entrega do Paddle 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 o primeiro passo do fluxo de trabalho ou restrinja os eventos que você envia do Paddle.
As solicitações falham com a mensagem “carimbo de data/hora fora da tolerância”▾
O Paddle assina um carimbo de data/hora e o aplicativo rejeita qualquer evento com mais de 5 minutos. Normalmente, trata-se de um problema de relógio no lado do remetente ou de uma entrega que o Paddle tentou novamente muito mais tarde com o carimbo de data/hora original. Novas tentativas da mesma solicitação original não são permitidas; solicite ao Paddle 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 da payload e inseri-los no Shopify Flow.
- Proteção contra entregas duplicadas - o que ocorre quando o Paddle tenta novamente uma entrega.
- Histórico e solução de problemas - o registro de todas as solicitações, com reprodução.