Verificação de webhooks assinados
Muitos serviços assinam os webhooks que enviam, para que o destinatário possa comprovar que uma solicitação realmente veio deles e não foi alterada durante o trajeto. Defina a autenticação de um webhook como HMAC e o aplicativo verificará essa assinatura antes que qualquer coisa chegue a Shopify Flow. Uma solicitação que não for aprovada na verificação é rejeitada com a mensagem 401 e nunca executa um fluxo de trabalho.
Existem duas maneiras de configurá-lo: selecione o remetente na lista ou descreva como ele assina.
Provedores integrados
Escolha o provedor na seção “Provedor de assinatura” e cole seu segredo de assinatura. O aplicativo verifica então se o provedor segue as especificações - cabeçalho correto, codificação, conteúdo assinado e janela de repetição - , de modo que não há mais nada a ser configurado. Cada provedor possui seu próprio guia de configuração, desde a criação do endpoint até a construção do fluxo de trabalho Shopify Flow.
Cada guia indica exatamente o que o aplicativo verifica em relação a esse remetente e onde encontrar seu segredo de assinatura.
Assinatura personalizada: qualquer outro remetente
Caso o remetente não conste na lista, selecione “Assinatura personalizada” e descreva como ela funciona. A documentação do seu provedor conterá uma linha como esta:
X-Acme-Signature = hex(hmac_sha256(secret, timestamp + "." + body))
Essa única linha preenche todos os campos:
| Cenário | A partir do exemplo | O que isso significa |
|---|---|---|
| Cabeçalho de assinatura | X-Acme-Signature |
O cabeçalho que contém a assinatura |
| Algoritmo | hmac_sha256 |
SHA-256, SHA-1 ou SHA-512 |
| Codificação | hex |
hex, base64 ou base64url |
| Payload assinado | {timestamp}.{body} |
O texto exato que foi assinado |
| Data e hora | um cabeçalho como X-Acme-Timestamp |
Por onde o valor de timestamp percorre |
| Tolerância à repetição | 300 segundos | Rejeitar solicitações mais antigas do que esta |
The signed payload
Escreva o que o remetente assina utilizando estes espaços reservados:
| Espaço reservado | Torna-se |
|---|---|
{body} |
O corpo bruto da solicitação, byte por byte. Obrigatório. |
{timestamp} |
O carimbo de data e hora do cabeçalho ou do cabeçalho da assinatura |
{url} |
A URL deste webhook, conforme você a inseriu no remetente |
{header:name} |
O valor de outro cabeçalho de solicitação |
Formatos comuns: {body}, {timestamp}.{body}, {timestamp}{body}, v0:{timestamp}:{body}, {header:webhook-id}.{timestamp}.{body}. Utilize a opção “Começar a partir de um provedor” para copiar um formato semelhante e altere apenas o que for diferente.
Onde fica a assinatura
- Simples: o valor do cabeçalho é a assinatura, opcionalmente seguida de um prefixo de sua escolha, como
sha256=ouv1,. - Chave = valor: o cabeçalho contém pares como
t=1700000000,v1=abc.... Indique o nome da chave que contém a assinatura (v1), opcionalmente o nome da chave que contém o carimbo de data e hora (t) e se os pares são separados por,ou;.
Se um cabeçalho contiver várias assinaturas separadas por espaços - o que alguns remetentes fazem ao alternar uma chave secreta - , qualquer uma que corresponda será aceita.
O segredo
Normalmente, você cola o segredo exatamente como o remetente o apresenta. Alguns remetentes fornecem uma chave codificada em base64 com um prefixo, como whsec_...: selecione a opção “codificada em base64” e insira o prefixo a ser removido.
Testes antes da entrada em operação
O verificador de assinatura fica abaixo das configurações e funciona com alterações não salvas.
- Cole o corpo e os cabeçalhos de uma solicitação real e clique em “Verificar”. Você verá cada etapa - cabeçalho encontrado, assinatura lida, carimbo de data/hora dentro do intervalo, payload construído, assinaturas comparadas - e o texto exato que foi assinado; assim, uma incompatibilidade indica onde ocorreu o erro, em vez de apenas exibir uma mensagem genérica como “assinatura inválida”.
- A opção “Gerar um exemplo válido” produz cabeçalhos assinados corretamente e um arquivo
curlpronto para execução, de acordo com suas configurações atuais. Se essa solicitação for aceita, sua configuração estará consistente de ponta a ponta.
O testador nunca inicia um fluxo de trabalho, não registra nada no Histórico e não é contabilizado no seu plano.
A assinatura não corresponde. O que devo verificar?▾
Nesta ordem: o segredo (a causa mais comum, incluindo um espaço a mais ou a chave do ambiente incorreto), a payload assinada (a ausência de . ou : entre o carimbo de data/hora e o corpo da mensagem), a codificação (hexadecimal vs. base64) e se algo entre o remetente e o aplicativo alterou o corpo da mensagem. As assinaturas abrangem os bytes brutos; portanto, um proxy que reformata o JSON as invalida.
As solicitações falham com a mensagem “carimbo de data/hora fora da tolerância”▾
O relógio do remetente está desajustado, a solicitação foi atrasada ou reenviada com um carimbo de data/hora desatualizado, ou a unidade do carimbo de data/hora está incorreta. Verifique se o seu remetente utiliza segundos, milissegundos ou uma data ISO.
Meu remetente precisa, primeiro, de um processo de verificação▾
Alguns serviços (Zoom, Dropbox, Asana, Trello, Notion) enviam uma solicitação de verificação à qual o endpoint precisa responder antes de transmitirem quaisquer eventos, cada um à sua maneira. Por esse motivo, eles não são oferecidos como provedores de “um clique”. Entre em contato com o suporte, informando o nome do remetente, caso precise de um desses serviços.
A assinatura está armazenada em algum lugar?▾
Não. Os cabeçalhos de assinatura são ocultados no Histórico e no Inspetor de Solicitações em Tempo Real, pois uma assinatura pode ser reproduzida dentro de sua janela de tolerância.