Falhas de Webhook no WooCommerce Subscriptions: Causas Reais e Soluções

Em 2024, fui contratado como Tech Lead de um e-commerce regulado no Canadá. Processadores de pagamento nesse setor são tensos; poucas empresas aceitam o risco, e as que aceitam te deixam sempre no limite de ter a conta encerrada por qualquer problema. Todo o modelo de negócio dependia de ser seguro e estável.

Assim que comecei, a primeira coisa que fiz foi checar os logs de webhooks.

Os logs diziam que o pedido estava pago. No painel do WooCommerce, a realidade era outra.

Esse abismo entre o que o gateway (como Stripe ou PayPal) reporta e o que o WooCommerce processa é onde mora a maioria das falhas de renovação de assinaturas. Tutoriais genéricos dizem para conferir a URL e as credenciais. Esse conselho é tecnicamente correto, mas inútil na prática: se a URL estivesse errada, você já saberia.

As falhas que realmente matam o faturamento recorrente são sutis e quase sempre arquiteturais.

O que Acontece Quando um Webhook Chega

Quando uma assinatura vence, seu gateway de pagamento dispara um webhook (um POST HTTP) para o seu site e espera uma resposta "200 OK" em poucos segundos. Do ponto de vista do gateway, é só isso: enviar dados, receber um OK e seguir a vida.

No seu lado, o WooCommerce Subscriptions recebe esses dados, verifica a assinatura, procura o registro no banco, processa o pagamento, atualiza o status, cria o pedido de renovação e dispara vários e-mails e hooks.

Tudo isso acontece simultaneamente durante a requisição do webhook.

Essa é a parte que muitos donos de loja ignoram. Seu site está rodando um fluxo completo de transação enquanto o gateway espera a resposta. Se algo demorar demais, der erro ou o banco de dados travar, o gateway não recebe o "OK". Ele vê um erro 500 ou um timeout. Então, ele agenda uma nova tentativa (retry).

O problema é que o retry só ajuda se o erro foi passageiro. Se for um erro de design do sistema, toda tentativa vai falhar da mesma forma.

Os Três Principais Modos de Falha

1. Falha por Timeout: Seu servidor está carregado, rodando 40 plugins em uma hospedagem compartilhada sem cache de objeto. O webhook chega, o processamento começa e leva 35 segundos. O limite do gateway é 30. Ele marca como falha. O detalhe: o WooCommerce pode ter terminado o processo com sucesso no segundo 31, mas o gateway não sabe disso e tenta cobrar de novo, gerando cobranças duplicadas ou pedidos em dobro.

2. Erro Durante o Processamento: Um plugin qualquer tenta rodar um código no momento em que o pagamento é confirmado, mas dá um erro fatal de PHP. O WooCommerce já atualizou o pagamento no banco, mas como houve o erro, o servidor retorna um erro 500 para o gateway. O gateway entende que falhou e tentará cobrar novamente. Esse erro é difícil de achar porque nos logs do WooCommerce tudo parece certo; você precisa olhar os logs de erros fatais do servidor para encontrar o vilão.

3. Estado de Assinatura Inconsistente: Um atendente alterou manualmente o status de uma renovação para ajudar um cliente. Quando o próximo pagamento automático chega via webhook, o WooCommerce encontra um estado que ele não esperava e simplesmente ignora a renovação. A assinatura expira sem ninguém notar até o cliente reclamar.

Como Rastrear a Causa Real

O diagnóstico exige comparar dois logs com os mesmos timestamps.

Pegue o log de entrega de webhooks no painel do seu gateway de pagamento. Ele mostra o que enviou e o que recebeu de volta. Depois, vá em WooCommerce > Status > Logs e procure pelo log woocommerce-subscriptions.

Compare os horários. Se o gateway mostra um erro 500, procure nos logs de erros fatais do PHP naquele exato segundo. Se mostra um timeout, analise a performance do seu servidor naquele horário.

Outro vilão comum: o wp-cron. O WooCommerce Subscriptions depende dele para agendar as renovações. Se o seu site tem pouco tráfego, o cron do WordPress pode não disparar no horário certo. A solução profissional é desabilitar o cron nativo e configurar um cron job real no nível do servidor.

A Solução é Arquitetural

Consertar as falhas uma a uma é enxugar gelo. A pergunta correta é: por que seu site está processando tudo de forma síncrona enquanto o gateway espera?

A solução definitiva é o processamento assíncrono. Quando o webhook chega, seu endpoint deve apenas registrar o recebimento em uma fila e retornar o "OK" imediatamente. Um processo em segundo plano cuida do resto. Se houver falha, você controla as tentativas de novo com logs claros e sem estressar o gateway de pagamento.

Além disso, seu sistema deve ser idempotente: ele deve ser capaz de identificar que já processou aquele ID de transação e não tentar cobrar ou criar um pedido repetido se o webhook chegar duas vezes.

Hospedagem rápida ajuda, mas não resolve o problema estrutural. O processamento assíncrono elimina o risco.

---

Se sua loja WooCommerce tem um volume considerável de assinaturas, esses ajustes arquiteturais devem ser feitos agora, antes que você comece a perder faturamento silenciosamente. Entenda como eu trabalho para resolver esses gargalos de infraestrutura e garantir a estabilidade do seu e-commerce.