Como configurar webhook Stripe com PHP 8.4 no Alpine Linux 3.22

Para configurar webhook Stripe com PHP 8.4 no Alpine Linux 3.22, crie um endpoint HTTPS em PHP que leia o payload bruto da requisição POST, valide a assinatura enviada no cabeçalho da Stripe e responda com HTTP 200 somente após confirmar a origem do evento. O processo funciona tanto em servidores dedicados quanto em ambientes containerizados com Docker, desde que as extensões PHP necessárias e o acesso HTTPS estejam configurados corretamente.

1. Prepare o Alpine Linux 3.22 com PHP 8.4, extensões necessárias, Composer e acesso SSH.
2. Crie um endpoint PHP que receba somente requisições POST do webhook Stripe.
3. Leia o corpo bruto com php://input e capture o cabeçalho de assinatura enviado pela Stripe.
4. Valide a assinatura com o segredo do webhook antes de alterar pedido, estoque ou assinatura.
5. Registre a URL HTTPS no painel da Stripe e ative apenas os eventos necessários ao e-commerce.
6. Teste eventos em ambiente de desenvolvimento, confira logs e só depois publique em produção.

Pré-requisitos para configurar webhook Stripe com PHP 8.4

Webhook Stripe em Alpine Linux exige uma base mínima bem definida, porque o endpoint precisa responder rápido, validar origem e manter rastreabilidade. Antes de escrever o PHP, confirme que o servidor executa Alpine Linux 3.22, que o PHP usado pela aplicação é o PHP 8.4 e que você tem permissão para instalar pacotes, criar arquivos em diretório web e configurar variáveis de ambiente. O Alpine é amplamente usado em containers Docker, por isso verifique também se as variáveis de ambiente do segredo estão disponíveis no contexto de execução — seja no host ou no container.

• Acesso SSH ao servidor Alpine Linux 3.22 com usuário autorizado a instalar pacotes.
• PHP 8.4 disponível para CLI e para o servidor web usado pela loja.
• Composer para instalar a biblioteca Stripe para PHP no projeto.
• Domínio apontando para o servidor, por exemplo seudominio.com.br.
• Endpoint HTTPS com certificado TLS válido em produção.
• Segredo do webhook gerado no painel da Stripe.
• Acesso aos logs do PHP e do servidor web para diagnóstico.
• Ambiente de teste separado da loja em produção.

Se o acesso ao servidor ainda não estiver pronto, use o artigo Acessando servidores VPS Linux da AviraHost como referência operacional. Para produção, também vale revisar Como redirecionar um site http para https?, pois o webhook Stripe deve ficar publicado em HTTPS.

Preparar PHP 8.4 no Alpine Linux 3.22

PHP 8.4 para webhook Stripe deve estar disponível tanto para executar scripts de teste quanto para atender requisições web. No Alpine, mantenha o ambiente enxuto: instale apenas o que o endpoint precisa, valide a versão carregada e separe o diretório do webhook do restante da aplicação. Isso reduz ruído ao analisar logs e evita que um erro de rota da loja seja confundido com erro de entrega do webhook.

Comece atualizando o índice de pacotes e instalando PHP 8.4, extensões comuns para chamadas HTTPS e Composer. Se o seu repositório Alpine 3.22 usa nomes de pacotes diferentes, mantenha a mesma lógica: PHP 8.4, suporte a OpenSSL, cURL, JSON decoding, mbstring, PHP-FPM quando houver servidor web e Composer.

apk update
apk add --no-cache php84 php84-cli php84-fpm php84-openssl php84-curl php84-json php84-mbstring composer curl

Output esperado:
índice de pacotes atualizado
PHP 8.4 e dependências instalados
Composer disponível no sistema

Agora confirme se o binário chamado no terminal é o PHP 8.4. Ao rodar este comando, você verá a versão ativa do PHP usada nos testes de linha de comando. Essa checagem evita configurar tudo corretamente no arquivo, mas executar os testes com outro PHP instalado no servidor.

php84 -v

Output esperado:
PHP 8.4.x
Copyright
Zend Engine

Crie a estrutura do projeto em um diretório dedicado. A pasta public será o ponto de entrada do endpoint, enquanto dependências e arquivos auxiliares devem ficar fora dela sempre que possível.

mkdir -p /srv/stripe-webhook/public
cd /srv/stripe-webhook

Output esperado:
sem saída se o diretório for criado com sucesso
diretório atual: /srv/stripe-webhook

Instalar a biblioteca Stripe para PHP no projeto

Endpoint Stripe em PHP 8.4 fica mais seguro quando a validação da assinatura não é improvisada. A comparação prática é simples: a abordagem com biblioteca reduz o risco de erro de implementação, enquanto a validação manual exige recriar corretamente o processo de conferência do cabeçalho, do payload bruto e do segredo. Para um e-commerce, a opção com biblioteca é normalmente a mais indicada, desde que você mantenha dependências atualizadas e trate exceções na aplicação.

1. Entre no diretório do projeto.
2. Instale a biblioteca Stripe para PHP com Composer.
3. Confirme se o diretório vendor foi criado.
4. Mantenha o autoload fora de qualquer pasta pública desnecessária.

cd /srv/stripe-webhook
composer require stripe/stripe-php

Output esperado:
dependência stripe/stripe-php resolvida
arquivos instalados em vendor
autoload do Composer gerado

Confira a estrutura. O arquivo vendor/autoload.php será carregado pelo endpoint. Se esse arquivo não existir, o PHP não conseguirá chamar a rotina de validação da assinatura e o webhook deve retornar erro antes de processar qualquer pagamento.

test -f vendor/autoload.php
echo $?

Output esperado:
0

Biblioteca Stripe para PHP ou validação manual: qual escolher?

Na prática, o comparativo favorece a biblioteca quando o objetivo é reduzir falhas de segurança. A validação manual só deve ser considerada quando existe um motivo técnico forte e equipe capaz de auditar a implementação, porque um pequeno erro no uso do payload bruto ou do cabeçalho de assinatura pode aceitar eventos falsos ou rejeitar eventos legítimos. Em ambiente de hospedagem de e-commerce, prefira a biblioteca, registre logs objetivos e mantenha o endpoint com responsabilidade única: receber, validar, identificar o evento e acionar a regra de negócio apropriada.

Criar o endpoint PHP do webhook Stripe

Configurar webhook Stripe com PHP começa pelo comportamento correto da rota. O endpoint deve aceitar POST, ler o corpo bruto com php://input, capturar o cabeçalho de assinatura, carregar o segredo por variável de ambiente e responder com código HTTP adequado. Não confie em dados do evento antes da validação e não coloque o segredo diretamente no código versionado.

Atenção: o próximo comando cria um arquivo em /etc/profile.d. Se já existir um arquivo com o mesmo nome, ele será substituído. Ajuste o valor do segredo usando o segredo real do webhook gerado no painel da Stripe.

cat > /etc/profile.d/stripe-webhook.sh <<'EOF'
export STRIPE_WEBHOOK_SECRET="whsec_substitua_pelo_segredo_real"
EOF
. /etc/profile.d/stripe-webhook.sh

Output esperado:
sem saída se a variável for gravada e carregada com sucesso

Crie o arquivo do endpoint. Este exemplo é intencionalmente direto: ele rejeita métodos diferentes de POST, rejeita requisições sem payload, assinatura ou segredo, valida o evento e processa apenas tipos necessários ao fluxo de e-commerce. Em produção, envolva a validação em tratamento de exceções compatível com o padrão da sua aplicação para retornar erro controlado quando a assinatura for inválida.

cat > /srv/stripe-webhook/public/stripe-webhook.php <<'PHP'
<?php
declare(strict_types=1);

require __DIR__ . "/../vendor/autoload.php";

if ($_SERVER["REQUEST_METHOD"] !== "POST"):
    http_response_code(405);
    echo "metodo nao permitido";
    exit;
endif;

$payload = file_get_contents("php://input");
$assinatura = $_SERVER["HTTP_STRIPE_SIGNATURE"] ?? "";
$segredo = getenv("STRIPE_WEBHOOK_SECRET") ?: "";

if ($payload === false):
    http_response_code(400);
    echo "payload ausente";
    exit;
endif;

if ($payload === ""):
    http_response_code(400);
    echo "payload vazio";
    exit;
endif;

if ($assinatura === ""):
    http_response_code(400);
    echo "assinatura ausente";
    exit;
endif;

if ($segredo === ""):
    http_response_code(500);
    echo "segredo nao configurado";
    exit;
endif;

$evento = \Stripe\Webhook::constructEvent($payload, $assinatura, $segredo);
$tipo = $evento->type ?? "";

$eventos_aceitos = [
    "checkout.session.completed",
    "payment_intent.succeeded",
    "payment_intent.payment_failed"
];

if (! in_array($tipo, $eventos_aceitos, true)):
    http_response_code(200);
    echo "evento ignorado";
    exit;
endif;

error_log("Stripe webhook recebido: " . $tipo);

http_response_code(200);
echo "ok";
PHP

Output esperado:
sem saída se o arquivo for criado com sucesso

Valide a sintaxe do PHP antes de publicar. Esse teste não confirma a assinatura, mas elimina erros de digitação, extensão ausente ou autoload inacessível.

php84 -l /srv/stripe-webhook/public/stripe-webhook.php

Output esperado:
No syntax errors detected in /srv/stripe-webhook/public/stripe-webhook.php

Publicar a URL HTTPS e registrar no painel da Stripe

Webhook Stripe HTTPS é obrigatório em produção porque o endpoint recebe informações sensíveis do fluxo de pagamento. A URL final deve ser estável, pública e servida com certificado TLS válido. Use um caminho específico, por exemplo https://seudominio.com.br/stripe-webhook.php, em vez de reaproveitar uma rota genérica da loja.

Antes de cadastrar a URL na Stripe, teste se o arquivo responde pelo servidor web. Se estiver usando o servidor embutido do PHP apenas para validação local, lembre-se de que ele não substitui a configuração definitiva de produção. Ele é útil para conferir o script, mas a loja deve usar o servidor web real com HTTPS.

cd /srv/stripe-webhook
php84 -S 127.0.0.1:8080 -t public

Output esperado:
PHP 8.4 Development Server started
Listening on http://127.0.0.1:8080

Em outro terminal, faça uma chamada sem assinatura válida. O resultado esperado é erro controlado, não processamento do pedido. Esse comportamento confirma que o endpoint não aceita chamadas anônimas sem validação.

curl -i -X POST http://127.0.0.1:8080/stripe-webhook.php --data-binary "teste"

Output esperado:
HTTP/1.1 400 Bad Request
assinatura ausente

1. No painel da Stripe, cadastre a URL HTTPS pública do endpoint.
2. Associe o segredo gerado pela Stripe à variável STRIPE_WEBHOOK_SECRET no ambiente web.
3. Ative apenas eventos usados pela regra de negócio da loja.
4. Envie eventos de teste antes de habilitar o fluxo real de pedidos.
5. Confirme se a resposta HTTP é adequada e se os logs registram o tipo de evento recebido.

Ao registrar a URL, evite processar todo tipo de evento apenas porque está disponível. Em e-commerce, quanto menor a superfície lógica, mais fácil fica auditar pagamento confirmado, pagamento recusado e mudanças no checkout ou no payment intent.

Testar eventos e logs antes da produção

Teste de webhook Stripe deve validar três pontos: recebimento da requisição, assinatura aceita e execução correta da regra de negócio. Um erro comum é testar somente se a URL abre no navegador; isso não prova que o endpoint recebe POST, nem que o payload bruto está intacto. O teste precisa simular evento real de webhook no ambiente de desenvolvimento ou sandbox.

Monitore os logs de erro do PHP durante o envio de eventos de teste. Ao rodar o comando abaixo, você deve ver mensagens registradas pelo endpoint, como o tipo do evento processado. Se nada aparecer, o problema pode estar na rota, no servidor web, na variável de ambiente do segredo ou na forma como o PHP-FPM carrega variáveis.

tail -f /var/log/php84/error.log

Output esperado:
Stripe webhook recebido: checkout.session.completed

Também confira se a porta HTTPS do servidor está escutando quando a publicação já estiver ativa. Use ss, que é a ferramenta moderna para inspeção de sockets em Linux.

ss -ltn

Output esperado:
State   Recv-Q Send-Q Local Address:Port
LISTEN  0      128    0.0.0.0:443
LISTEN  0      128    0.0.0.0:80

Depois do teste, revise a regra de negócio. O webhook deve ser idempotente: receber o mesmo evento mais de uma vez não pode duplicar pedido, liberar produto duas vezes ou alterar estoque incorretamente. Mesmo com assinatura válida, trate o evento como uma mensagem externa que precisa ser conferida contra o estado atual do pedido na aplicação.

Problemas comuns e como resolver

Sintoma: webhook retorna assinatura ausente

Causa: a requisição chegou sem o cabeçalho de assinatura esperado ou algum proxy removeu cabeçalhos antes de entregar ao PHP.

Solução: teste o endpoint a partir do painel da Stripe, confira os logs do servidor web e confirme se a aplicação lê $_SERVER["HTTP_STRIPE_SIGNATURE"]. Não tente contornar esse erro ignorando a assinatura.

Sintoma: endpoint funciona no terminal, mas falha no servidor web

Causa: a variável STRIPE_WEBHOOK_SECRET foi carregada na sessão SSH, mas não no ambiente usado pelo PHP-FPM ou pelo processo web.

Solução: configure a variável no ambiente do serviço que executa PHP e reinicie o serviço web correspondente. Depois, envie um evento de teste e confira se o erro mudou de segredo ausente para validação ou processamento.

Sintoma: Stripe recebe erro 405 Method Not Allowed

Causa: a rota está recebendo método diferente de POST ou existe redirecionamento incorreto convertendo a chamada.

Solução: cadastre exatamente a URL do arquivo PHP e garanta que o HTTPS não redirecione para outro caminho. O webhook não deve depender de navegação de browser, formulário HTML ou rota que aceite apenas GET.

Sintoma: evento é recebido, mas pedido não é atualizado

Causa: o tipo do evento não está na lista de eventos aceitos ou a regra de negócio da loja não está vinculada ao identificador correto do pedido.

Solução: registre no log o tipo de evento recebido, mantenha apenas os eventos necessários e valide o vínculo entre checkout, payment intent e pedido interno antes de atualizar status, estoque ou entrega.

Perguntas frequentes sobre webhook Stripe com PHP 8.4

Como configurar webhook Stripe com PHP 8.4 no Alpine Linux 3.22?

Para configurar webhook Stripe com PHP 8.4 no Alpine Linux 3.22, crie um endpoint HTTPS em PHP, leia o payload bruto da requisição e valide a assinatura enviada no cabeçalho do Stripe. Depois, registre a URL do endpoint no painel da Stripe e teste eventos de pagamento antes de usar em produção.

Preciso validar a assinatura do webhook Stripe em PHP?

Sim, a validação da assinatura é essencial para confirmar que o evento recebido foi realmente enviado pela Stripe. Sem essa verificação, qualquer cliente externo poderia simular chamadas para o endpoint e acionar ações indevidas no e-commerce.

O webhook Stripe precisa de HTTPS para funcionar em produção?

Sim, em ambiente de produção o endpoint do webhook deve usar HTTPS com certificado TLS válido. Isso protege o tráfego entre a Stripe e o servidor, além de evitar falhas de entrega relacionadas a conexões inseguras.

Quais eventos Stripe devo ativar para um e-commerce?

Para e-commerce, normalmente faz sentido tratar eventos ligados ao ciclo do pagamento, como confirmação, falha e atualização de checkout ou payment intent. A escolha exata depende do fluxo da loja, mas o endpoint PHP deve processar apenas os eventos necessários para evitar lógica excessiva.

Como testar um webhook Stripe antes de colocar a loja em produção?

O teste deve ser feito em modo de desenvolvimento ou sandbox, enviando eventos de teste para o endpoint configurado. Verifique os logs do PHP e do servidor web para confirmar status HTTP adequado, validação da assinatura e execução correta da regra de negócio.

Conclusão

Webhook Stripe para e-commerce em PHP 8.4 no Alpine Linux 3.22 deve ser tratado como uma integração crítica, não como uma simples URL que recebe POST. A configuração correta combina HTTPS, payload bruto, segredo fora do código, validação de assinatura e logs suficientes para auditoria.

• Use biblioteca Stripe para PHP sempre que possível e evite validação manual sem auditoria técnica.
• Cadastre no painel da Stripe apenas eventos necessários ao ciclo de pagamento da loja.
• Teste em ambiente separado, acompanhe logs e confirme respostas HTTP antes de liberar produção.

Leia também

• checklist configurar webhook GitHub em Nginx: exemplo real
• Otimizar Home Assistant no Alpine Linux 3.22: do zero ao funcionando
• Cache FastCGI no Alpine Linux 3.22: guia WordPress com Nginx

Precisa de ajuda para hospedar sua aplicação PHP com webhook Stripe?

A AviraHost pode ajudar a preparar o ambiente PHP, HTTPS e hospedagem da sua aplicação para receber webhooks de e-commerce com mais previsibilidade. Uma base bem configurada reduz retrabalho na integração e facilita o diagnóstico quando eventos de pagamento precisam ser auditados.

Conheça as opções de hospedagem para sua aplicação PHP