Como conectar o Calendly ao Shopify Flow
O Calendly envia um Webhook quando uma reunião é agendada ou cancelada por meio de um de seus tipos de evento. O Workflow Webhooks transforma essa chamada em um gatilho do Shopify Flow, para que sua loja possa reagir a ela: atribuir uma tag a 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 - o Calendly envia, Workflow Webhooks recebe e verifica, Shopify Flow executa - com a assinatura HMAC do Calendly verificada em cada solicitação, de modo que somente o Calendly possa iniciar seu fluxo de trabalho.
O que o(a) senhor(a) pode construir
- Marque um cliente que agendou uma consulta de estilo ou uma ligação de orientação, para que possa segmentá-lo posteriormente.
- Adicione uma nota do cliente com o horário da reunião antes da ligação ocorrer.
- Envie um e-mail ao funcionário responsável com o histórico de pedidos do cliente no site Shopify assim que a reserva for recebida.
Eventos típicos a serem enviados: invitee.created (reservado), invitee.canceled.
Antes de começar
- Workflow Webhooks instalado na sua loja do Shopify.
- Shopify Flow instalado, que pode ser baixado gratuitamente na Loja da App Store do Shopify.
- Uma conta no Calendly 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
Calendly events. - Na seção “Autenticação”, selecione HMAC.
- Na seção “Provedor de assinatura”, selecione o Calendly. 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 ser configurado.
- 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 Calendly
Crie uma assinatura do webhook por meio da API do Calendly ou do portal do desenvolvedor com a URL que você copiou. A chave de assinatura é retornada uma única vez, quando a assinatura é criada.
Como localizar seu segredo de assinatura do Calendly
A chave de assinatura fornecida quando o senhor criou a assinatura do webhook.
A própria documentação do Calendly sobre assinaturas de webhooks contém o texto exato e as capturas de tela referentes à sua conta.
Cole esse segredo no campo “Secret” do webhook em Workflow Webhooks e salve. A partir desse momento, todas as notificações do Calendly serão verificadas antes de chegarem ao Shopify Flow.
O que isso verifica
| O que | Valor |
|---|---|
| Cabeçalho de assinatura | Calendly-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 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 6 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} corresponde ao corpo bruto da solicitação, byte a byte, e {timestamp} corresponde ao 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 “Registrar eventos” e, em seguida, envie um evento de teste pelo Calendly (ou utilize 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 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 aplique apenas ao Calendly. 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 Calendly. Em Workflow Webhooks -> Histórico, vocês deverão ver a chamada com o status “Sucesso”. Caso a assinatura esteja incorreta, será exibida uma entrada com status de falha, acompanhada do motivo; e 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▾
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 Calendly 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 Calendly selecionado, se o segredo está preenchido e se o Calendly 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 Calendly e consulte o próprio registro de entrega do Calendly para verificar 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 primeira etapa do fluxo de trabalho ou restrinja os eventos que você envia do Calendly.
As solicitações falham com a mensagem “carimbo de data/hora fora da tolerância”▾
O Calendly assina um carimbo de data e hora, e o aplicativo rejeita qualquer mensagem com mais de 6 minutos. Normalmente, isso se deve a um problema de relógio no lado do remetente ou a uma entrega que o Calendly tentou novamente muito mais tarde, mantendo o carimbo de data e hora original. Novas tentativas decorrentes da mesma solicitação original não são permitidas; solicite ao Calendly 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 Calendly tenta novamente a entrega.
- Histórico e solução de problemas - o registro de todas as solicitações, com reprodução.