Um segredo de assinatura de webhook é uma chave compartilhada que permite ao Provedly confirmar que um evento de compra realmente veio do Stripe ou do Shopify e não foi alterado no caminho. É o motivo pelo qual o Provedly consegue colocar a marca "Compra verificada" numa notificação: a marca significa que a assinatura conferiu. Este artigo explica o que é um webhook, o que a assinatura faz, como conectar cada plataforma e o que o segredo pode e não pode fazer se vazar.
Webhooks em um parágrafo. Quando algo acontece na sua plataforma de pagamento, como um pedido concluído, a plataforma pode enviar uma requisição HTTP para uma URL que você indica, com os detalhes no corpo. Essa requisição é um webhook. É a plataforma levando a novidade ao Provedly, em vez de o Provedly ficar perguntando repetidamente. No Shopify, o evento relevante é orders/create. No Stripe, costuma ser checkout.session.completed ou payment_intent.succeeded.
O problema de qualquer URL que aceita um POST é que qualquer pessoa pode enviar um POST para ela. Sem uma verificação, alguém poderia enviar ao Provedly um "pedido" falso e fazê-lo aparecer como real. A assinatura é essa verificação.
O que a assinatura faz
Tanto o Stripe quanto o Shopify assinam cada webhook com HMAC-SHA256. A plataforma pega o corpo bruto da requisição, calcula um hash usando um segredo que só ela e você conhecem e envia o hash num cabeçalho. O Provedly recalcula o hash com o mesmo segredo e compara. Se baterem, duas coisas ficam estabelecidas de uma vez: a requisição veio de alguém que tem o segredo, e o corpo não foi modificado no caminho.
Se não baterem, a requisição é descartada. Ela não é exibida, não é guardada como compra e não é contada. Não existe uma categoria de "compra não verificada". Existem compras verificadas, que passaram por essa verificação, e existem registros que o lojista adicionou de outro jeito, que sempre levam um rótulo: "Sample" para linhas adicionadas à mão, "Imported" para linhas de um CSV ou da Records API. Não há nada no meio.
Essa é toda a base da marca "Compra verificada", e é por isso que podemos informar na página de verificação pública quais origens estão conectadas e quando chegou a última compra verificada. /pt/blog/reading-the-verification-page explica como um comprador lê essa página.
Conectando o Shopify
Se você instalou o Provedly pela Shopify App Store, não precisa lidar com o segredo. O Shopify registra os webhooks quando o app é instalado e os assina com um segredo vinculado ao app. O Provedly os verifica automaticamente. A configuração está em /pt/blog/shopify-setup-guide.
Uma coisa a saber: por causa do programa Protected Customer Data do Shopify, os primeiros webhooks podem chegar sem o nome do comprador. Eles continuam assinados e verificados; a notificação simplesmente diz "Someone" até o acesso ser aprovado. /pt/blog/shopify-someone-protected-customer-data traz os detalhes.
Conectando o Stripe
Para sites fora do Shopify, você cria um endpoint de webhook no painel do Stripe apontando para a URL que o Provedly informa, seleciona os eventos, e o Stripe mostra um segredo de assinatura para esse endpoint. Ele começa com whsec_. Você o cola uma vez nas configurações da origem no Provedly.
Alguns pontos para fazer isso bem.
- Use um endpoint dedicado. Crie um endpoint novo para o Provedly em vez de reaproveitar um que a sua própria aplicação escuta. Cada endpoint tem seu próprio segredo, então um problema em um não afeta o outro.
- Selecione só os eventos de que você precisa. O Provedly precisa de pagamentos concluídos. Não precisa de atualizações de clientes, disputas nem repasses.
- Modo live, não modo de teste. Eventos do modo de teste são assinados com outro segredo e descrevem pagamentos que não aconteceram. Conecte um endpoint em modo live ao seu site de produção, para que pagamentos de teste nunca sejam apresentados como reais.
- Cole uma vez. Depois de salvar, considere o segredo guardado. Se você perder o controle dele, gere um novo no Stripe e cole o novo valor.
Contra o que o segredo protege
| Ameaça | A assinatura impede? |
|---|---|
| Alguém enviando um pedido falso por POST para a sua URL do Provedly | Sim |
| Um proxy alterando o valor ou o produto no caminho | Sim |
| Reenviar um evento antigo e verdadeiro | Em grande parte; as duas plataformas incluem timestamps e identificadores de evento, que permitem rejeitar eventos antigos ou duplicados |
| Alguém com o seu login do painel do Stripe criando reembolsos ou pagamentos reais | Não; isso é segurança da conta, não segurança do webhook |
A última linha importa. O segredo de assinatura verifica que os eventos vieram da plataforma. Ele não torna a própria plataforma confiável e não substitui a autenticação em dois fatores na sua conta do Stripe ou do Shopify.
Se o segredo vazar
Um segredo de assinatura do Stripe vazado permite que alguém falsifique eventos de webhook para o endpoint a que ele pertence. No caso do Provedly, isso significaria compras verificadas falsas, que é exatamente o resultado que todo o sistema existe para impedir. A solução é rápida: no Stripe, gere um novo segredo para aquele endpoint, o que invalida o antigo na hora, e cole o novo valor no Provedly.
O segredo não pode ser usado para cobrar cartões, ler dados de clientes nem entrar no Stripe. Ele serve apenas para assinar eventos de um endpoint. É por isso que é seguro um lojista lidar com ele, e por isso pedimos o segredo em vez de um acesso mais amplo à API.
No Shopify, o segredo do app fica com o Provedly e com o Shopify, não com o lojista, então não há nada que o lojista possa vazar ou trocar.
Por que isso importa para a categoria
A maioria das ferramentas desta categoria, em outubro de 2026 e segundo as próprias páginas, aceita dados digitados pelo lojista para notificações e contagens de visitantes e não os diferencia visualmente dos dados vindos da plataforma. Algumas verificam webhooks, mas depois exibem linhas importadas de CSV no mesmo estilo. A assinatura só é útil se o produto a tratar como fronteira: assinado de um lado, rotulado como Imported ou Sample do outro, e nenhum jeito de mover uma linha de um lado para o outro.
Essa fronteira é o que a regra da FTC sobre depoimentos falsos, em vigor desde o fim de 2024, implicitamente pede que os lojistas consigam demonstrar. Um webhook assinado é o mais perto de um comprovante que uma notificação de prova social pode carregar.
Perguntas frequentes
Posso conectar o Shopify e o Stripe a um mesmo site?
Sim. Uma loja Shopify que também vende por um checkout com Stripe fora do Shopify pode conectar os dois. A página de verificação lista os dois como origens, e as compras de cada um são verificadas de forma independente.
O webhook contém números de cartão?
Não. Nem o Stripe nem o Shopify incluem dados de cartão nos webhooks de pedidos ou pagamentos. O que o Provedly precisa para uma notificação é o produto, o primeiro nome quando informado, uma localização aproximada e o horário.
E se a minha conta do Stripe estiver em modo de teste enquanto eu monto o site?
Mantenha os eventos do modo de teste longe do seu site de produção. Quando entrar no ar, crie um endpoint em modo live no Stripe e conecte esse, para que só pagamentos reais possam virar compras verificadas.
Conecte hoje uma origem assinada e deixe a marca "Compra verificada" fazer o seu trabalho; os planos estão em /pt/pricing.