Verificação de webhooks assinados
Muitos serviços assinam os webhooks que enviam, para que o destinatário possa comprovar que um pedido provém efetivamente deles e não foi alterado durante o percurso. Defina a autenticação de um webhook como HMAC e a aplicação verificará essa assinatura antes de qualquer coisa chegar a Shopify Flow. Um pedido que não passe na verificação é rejeitado com o erro 401 e nunca executa um fluxo de trabalho.
Existem duas formas de configurar isto: selecione o remetente da lista ou descreva a forma como este assina.
Provedores integrados
Selecione o fornecedor na secção «Fornecedor de assinatura» e cole o seu segredo de assinatura. A aplicação verifica então a forma como esse fornecedor documenta os dados - o cabeçalho correto, a codificação, o conteúdo assinado e a janela de repetição - pelo que não há mais nada a configurar. Cada fornecedor dispõe do seu próprio guia de configuração, desde a criação do ponto de extremidade até à construção do fluxo de trabalho Shopify Flow.
Cada guia indica exatamente o que a aplicação verifica relativamente a esse remetente e onde encontrar o seu segredo de assinatura.
Assinatura personalizada: qualquer outro remetente
Se o seu remetente não constar da lista, selecione «Assinatura personalizada» e descreva como é que este assina. A documentação do seu fornecedor conterá uma linha do tipo:
X-Acme-Signature = hex(hmac_sha256(secret, timestamp + "." + body))
Essa única linha preenche todos os campos:
| Contexto | A partir do exemplo | O que isso significa |
|---|---|---|
| Cabeçalho da 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 |
Para onde se desloca o valor de timestamp |
| Tolerância de repetição | 300 segundos | Rejeitar os pedidos mais antigos do que este |
The signed payload
Escreva o que o remetente assina utilizando estes espaços reservados:
| Espaço reservado | Torna-se |
|---|---|
{body} |
O corpo da solicitação em formato bruto, byte a byte. Obrigatório. |
{timestamp} |
O carimbo temporal do cabeçalho ou do cabeçalho da assinatura |
{url} |
O URL deste webhook, tal como o introduziu no remetente |
{header:name} |
O valor de outro cabeçalho de pedido |
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 fornecedor» para copiar um formato semelhante e altere apenas o que difere.
Onde se encontra a assinatura
- Simples: o valor do cabeçalho é a assinatura, opcionalmente seguida de um prefixo que definir, tal como
sha256=ouv1,. - Chave = valor: o cabeçalho contém pares como
t=1700000000,v1=abc.... Indique a chave que contém a assinatura (v1), opcionalmente a chave que contém o carimbo temporal (t), e se os pares são separados por,ou;.
Se um cabeçalho contiver várias assinaturas separadas por espaços - o que acontece com alguns remetentes quando se altera um segredo - , qualquer uma que corresponda é aceite.
O segredo
Normalmente, deve colar o segredo tal 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 introduza o prefixo a remover.
Testes antes da entrada em funcionamento
O verificador de assinatura encontra-se abaixo das definições e funciona com alterações não guardadas.
- Cole o corpo e os cabeçalhos de um pedido real e clique em «Verificar». Obterá cada etapa - cabeçalho encontrado, assinatura lida, carimbo temporal dentro do intervalo, payload criado, assinaturas comparadas - e o texto exato que foi assinado; assim, uma discrepância indica-lhe onde ocorreu o erro, em vez de se limitar a uma simples mensagem do tipo «assinatura inválida».
- A função «Gerar um exemplo válido» produz cabeçalhos devidamente assinados e um ficheiro
curlpronto a ser executado, de acordo com as suas definições atuais. Se esse pedido for aceite, a sua configuração é consistente de ponta a ponta.
O testador nunca inicia um fluxo de trabalho, não regista nada no Histórico e não é contabilizado no seu plano.
A assinatura não corresponde. O que devo verificar?▾
Por este pedido: o segredo (a causa mais comum, incluindo um espaço extra ou a chave do ambiente errado), a carga útil assinada (a ausência de . ou : entre o carimbo de data/hora e o corpo), a codificação (hex vs. base64) e se algo entre o remetente e a aplicação alterou o corpo. As assinaturas abrangem os bytes em bruto, pelo que um proxy que reformate o JSON as invalida.
Os pedidos falham com a mensagem «carimbo temporal fora da tolerância»▾
O relógio do remetente está desajustado, o pedido foi atrasado ou repetido com um carimbo temporal antigo, ou a unidade do carimbo temporal está errada. Verifique se o seu remetente utiliza segundos, milissegundos ou uma data ISO.
O meu remetente necessita, em primeiro lugar, de um processo de verificação▾
Alguns serviços (Zoom, Dropbox, Asana, Trello, Notion) enviam um desafio de verificação ao qual o ponto final tem de responder antes de estes transmitirem quaisquer eventos, cada um à sua maneira. Por esse motivo, não são disponibilizados como prestadores de serviço com um único clique. Contacte o suporte indicando o nome do seu remetente, caso necessite de um desses serviços.
A assinatura está guardada em alguma loja?▾
Não. Os cabeçalhos das assinaturas são ocultados no Histórico e no Inspecionador de Pedidos em Tempo Real, uma vez que uma assinatura pode ser reproduzida dentro da sua janela de tolerância.