Autenticação

Qualquer pessoa que conheça o URL de um webhook pode enviar-lhe um pedido; por isso, a autenticação é o que impede que um estranho acione os seus fluxos de trabalho do Shopify Flow. Defina-a para cada webhook, na secção «Segurança» do respetivo webhook.

Os três métodos

Método	Como é que o autor da chamada comprova a sua identidade	Utilize-o quando
Nenhum	Nada	Apenas para testes - nunca em produção
Token estático	Um segredo fixo num cabeçalho de pedido	Quase todas as integrações (n8n, Make, Zapier, o seu próprio código)
HMAC SHA-256	Uma assinatura calculada a partir do pedido e de um segredo partilhado	O remetente assina os seus webhooks (Stripe, GitHub, Slack, …)

Token estático

Clique no botão «Gerar» no webhook para obter um token aleatório seguro ou cole o seu próprio token. O remetente envia-o num cabeçalho:

curl -X POST https://your-app-url/webhook/ab12cd34 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-token" \
  -d '{"orderId":"1001"}'

Alterar o nome do cabeçalho

Alguns sistemas só podem enviar um cabeçalho que já utilizam. Defina o nome do cabeçalho «Auth» nas «Definições avançadas» e iremos ler o token a partir desse cabeçalho, em vez de X-Api-Key:

  -H "X-Custom-Auth: your-token"

Os nomes dos cabeçalhos não distinguem maiúsculas de minúsculas. Os nomes reservados são rejeitados - Host, Authorization, Cookie, X-Forwarded-*, X-Webhook-*, CF-* e similares. Estes são definidos ou reescritos por proxies e CDNs, pelo que um token lido a partir de um deles seria controlável por um atacante.

Por onde passa o token

Nem todos os remetentes podem adicionar um cabeçalho arbitrário. Como é que o remetente transmite o token? No separador «Webhook» são apresentadas quatro opções:

Escolha	O remetente envia	Utilize-o quando
Num cabeçalho personalizado	X-Api-Key: <token> ou o nome do cabeçalho que escolher	A configuração predefinida e o que a maioria das integrações faz
Como um token ao portador	Authorization: Bearer <token>	A ferramenta dispõe de um campo «Bearer» ou «API-token»
Como nome de utilizador e palavra-passe	HTTP Basic, com um nome de utilizador à sua escolha e o token como palavra-passe	A ferramenta apenas disponibiliza a autenticação básica
Na URL	?token=<token> ou o nome do parâmetro que escolher	O remetente só pode aceder a um URL simples e não pode definir cabeçalhos

Authorization mantém propositadamente um nome de cabeçalho personalizado reservado: «Bearer» e «Basic» são as formas de suporte suportadas de o utilizar, e ambas são geridas automaticamente. Uma autenticação 401 nestas duas formas também inclui um cabeçalho WWW-Authenticate, uma vez que vários clientes HTTP só enviam credenciais após serem solicitados a fazê-lo.

A opção URL é a mais vulnerável das quatro - os URLs acabam por constar nos registos, nas referências e no histórico do navegador - pelo que deve utilizá-la apenas quando o remetente não lhe deixar outra alternativa. A aplicação apresenta o URL final com o token incluído e oculta esse parâmetro em todos os locais onde armazena o pedido.

HMAC SHA-256

O remetente calcula uma assinatura sobre o pedido utilizando um segredo partilhado; nós recalculamo-la e comparamo-la. Um pedido que tenha sido divulgado não pode ser reproduzido com conteúdo alterado, uma vez que o corpo do pedido já não corresponde à assinatura.

Predefinições do fornecedor

Selecione o seu remetente na secção «Fornecedor de assinaturas» e nós verificamos utilizando o esquema exato desse fornecedor - nome do cabeçalho, codificação, o que é assinado e durante quanto tempo a assinatura permanece válida. Cole o segredo de assinatura a partir do painel de controlo do fornecedor e está tudo pronto.

Existem 22 fornecedores integrados, cada um com o seu próprio guia de configuração: Calendly, Customer.io, GitHub, Lemon Squeezy, Linear, Mollie, Paddle, Paystack, Razorpay, Sanity, Sendcloud, Sentry, Shopify, Slack, Square, Webhooks Padrão (OpenAI, Supabase), Stripe, Svix (Clerk, Resend), Typeform, Vercel, WooCommerce e Zendesk. Caso o seu não conste da lista, descreva como é que este se autentica através de um esquema personalizado.

Consulte Verificação de webhooks assinados para obter a lista completa, a opção personalizada e o verificador de assinaturas integrado.

HMAC genérico

Na ausência de um esquema predefinido ou personalizado, utilizamos o nosso próprio: o remetente envia X-Signature, ou seja, o HMAC-SHA256 dos valores do cabeçalho X-Webhook-*, utilizando o segredo de assinatura.

curl -X POST https://your-app-url/webhook/ab12cd34 \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Data: value1value2" \
  -H "X-Signature: <hmac-sha256 of the X-Webhook-* values>" \
  -d '{"data":"payload"}'

Como se apresenta uma rejeição

A autenticação falhada devolve um código de erro 401, com um corpo JSON que indica o motivo - consulte Histórico e resolução de problemas para obter a lista completa de códigos. As chamadas rejeitadas continuam a aparecer no «Live Request Inspector» enquanto estiver a editar o webhook, para que possa ver exatamente por que razão uma chamada foi rejeitada.

Rotar a chave secreta sem tempo de inatividade

Alterar um segredo num único passo significa que todos os pedidos assinados com o segredo antigo falharão até que o remetente se atualize. A rotação do segredo no webhook evita isso: mantém um segundo segredo válido que é aceite a par do principal, tanto para o token estático como para todos os esquemas de assinatura.

1. Introduza o novo código secreto no campo «Segundo código secreto válido» e guarde. Ambos são agora aceites.
2. Altere o remetente para o novo segredo.
3. Clique em «Promover», o que o move para o campo principal e limpa o segundo, e guarde.

Nenhuma solicitação é rejeitada em momento algum. O segundo segredo é armazenado exatamente da mesma forma que o principal e nunca é devolvido pela API - apenas se foi ou não definido.

Manter o segredo em segurança

• O token nunca é devolvido pela nossa API REST ou pelo servidor MCP, independentemente do nível de acesso - estes indique apenas se algum está definido. Consulte API para programadores e MCP.
• Está encriptado em repouso.
• A rotação tem efeito imediato, pelo que deve utilizar o segundo Shopify Flow acima, em vez de sobrescrevendo o campo principal.
• O histórico de invocações guardado oculta o cabeçalho de autenticação, as credenciais Basic e o token da URL, Assim, uma captura de ecrã do Histórico não revela o seu segredo.

Restringir ainda mais

A autenticação comprova que quem efetua a chamada conhece o segredo. A autenticação de origem (Listas de endereços IP autorizados) restringe a origem de onde uma chamada pode provir e pode ser combinada com qualquer um dos modos acima referidos.