Autenticação

Qualquer pessoa que conheça a URL de um webhook pode enviar uma solicitação a ele; portanto, a autenticação é o que impede que um estranho acione seus fluxos de trabalho do Shopify Flow. Configure-a para cada webhook, na seção “Segurança” do respectivo webhook.

Os três métodos

Método	Como o chamador comprova sua identidade	Utilize-o quando
Nenhum	Nada	Apenas para testes - nunca em produção
Token estático	Um segredo fixo em um cabeçalho de solicitação	Praticamente todas as integrações (n8n, Make, Zapier, seu próprio código)
HMAC SHA-256	Uma assinatura calculada a partir da solicitação e de um segredo compartilhado	O remetente assina 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 o envia em um 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"}'

Alteração do nome do cabeçalho

Alguns sistemas só podem enviar um cabeçalho que já utilizam. Defina o nome do cabeçalho de autenticação nas Configurações avançadas e leremos 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 diferenciam maiúsculas de minúsculas. Nomes reservados são rejeitados - Host, Authorization, Cookie, X-Forwarded-*, X-Webhook-*, CF-* e similares. Esses nomes são definidos ou reescritos por proxies e CDNs; portanto, um token lido a partir de um deles estaria sob o controle de um invasor.

Por onde o token passa

Nem todo remetente pode adicionar um cabeçalho arbitrário. Como o remetente transmite o token? A aba “Webhook” oferece quatro opções:

Escolha	O remetente envia	Utilize-o quando
Em um cabeçalho personalizado	X-Api-Key: <token> ou o nome do cabeçalho que o(a) senhor(a) escolher	A configuração padrão, e o que a maioria das integrações faz
Como um token ao portador	Authorization: Bearer <token>	A ferramenta possui um campo “Bearer” ou “API-token”
Como nome de usuário e senha	HTTP Basic, com um nome de usuário de sua escolha e o token como senha	A ferramenta oferece apenas autenticação básica
Na URL	?token=<token> ou o nome do parâmetro que o(a) senhor(a) escolher	O remetente só pode acessar uma URL simples e não pode definir cabeçalhos

Authorization mantém propositalmente um nome de cabeçalho personalizado reservado: “Bearer” e “Basic” são as formas compatíveis de uso, e ambas são tratadas automaticamente para você. Uma autenticação 401 nessas duas formas também inclui um cabeçalho WWW-Authenticate, pois vários clientes HTTP só enviam credenciais após receberem uma solicitação de autenticação.

A opção de URL é a mais vulnerável das quatro - as URLs acabam aparecendo em logs, referenciadores e no histórico do navegador - , portanto, utilize-a apenas quando o remetente não lhe deixar outra escolha. O aplicativo exibe a URL finalizada com o token incluído e oculta esse parâmetro em todos os locais onde armazena a solicitação.

HMAC SHA-256

O remetente calcula uma assinatura sobre a solicitação utilizando um segredo compartilhado; nós a recalculamos e comparamos. Uma solicitação vazada não pode ser reproduzida com conteúdo alterado, pois o corpo da solicitação não corresponde mais à assinatura.

Configurações pré-definidas do provedor

Selecione o seu remetente na seção “Provedor de assinatura” e nós faremos a verificação utilizando o esquema exato desse provedor - nome do cabeçalho, codificação, o que é assinado e por quanto tempo a assinatura permanece válida. Cole o segredo de assinatura a partir do painel de controle do provedor e pronto.

Existem 22 provedores integrados, cada um com 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 provedor não esteja na lista, descreva como ele realiza a autenticação por meio de um esquema personalizado.

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

HMAC genérico

Na ausência de um esquema predefinido ou personalizado, utilizamos o nosso próprio: o remetente envia X-Signature, 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 malsucedida retorna 401 com um corpo JSON indicando o motivo - consulte Histórico e solução de problemas para obter a lista completa de códigos. As chamadas rejeitadas ainda aparecem no Live Request Inspector enquanto você estiver editando o webhook, para que você possa ver exatamente por que uma delas foi rejeitada.

Rotação da chave secreta sem tempo de inatividade

Alterar um segredo em uma única etapa significa que todas as solicitações assinadas com o segredo antigo falharão até que o remetente se atualize. A rotação do segredo no webhook evita isso: ele mantém um segundo segredo válido que é aceito juntamente com o principal, tanto para o token estático quanto para todos os esquemas de assinatura.

1. Insira a nova senha em “Segunda senha válida” e salve. Agora, ambas são aceitas.
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 salve.

Nenhum pedido é rejeitado em nenhum momento. O segundo segredo é armazenado exatamente da mesma forma que o principal e nunca é retornado pela API - apenas é informado se ele está definido.

Mantendo o segredo em segurança

• O token nunca é devolvido pela nossa API REST ou pelo servidor MCP em nenhum nível de acesso - eles informe apenas se algum deles estiver definido. Consulte API para desenvolvedores e MCP.
• Os dados são criptografados em repouso.
• A rotação entra em vigor imediatamente; portanto, utilize o segundo Shopify Flow descrito acima, em vez de sobrescrevendo o campo principal.
• O histórico de invocações armazenado oculta o cabeçalho de autenticação, as credenciais Basic e o token da URL, Portanto, uma captura de tela do Histórico não revela o seu segredo.

Restringindo ainda mais

A autenticação comprova que o autor da chamada conhece o segredo. A autenticação de origem (Listas de endereços IP permitidos) restringe a origem de uma chamada e pode ser combinada com qualquer um dos modos acima.