O problema
Muitas lojas enviam pedidos, produtos ou clientes a outros sistemas pelos webhooks nativos do WooCommerce. Se o sistema que recebe fica fora do ar, devolve erro ou demora demais, a loja continua vendendo e o outro sistema para de receber. Ninguém é avisado: você descobre quando estoque, notas ou envios saem de sincronia.
O que o WooCommerce faz quando um webhook falha repetidamente
- O WooCommerce conta as falhas de entrega consecutivas (qualquer resposta diferente de 2xx, 301 ou 302). Quando o limite é ultrapassado (valor padrão do filtro: 5; no WooCommerce 11.2.2 o status muda na 7ª falha seguida), o status passa a Desativado.
- Ele não envia e-mail nem mostra aviso quando isso acontece (verificado no WooCommerce 11.2.2). O status só aparece em WooCommerce › Configurações › Avançado › Webhooks, e as entregas ficam em Status › Logs.
- Os eventos ocorridos enquanto o webhook está desativado não são enviados depois. Reativar não os reenvia.
- O contador de falhas só zera com uma entrega bem-sucedida, não na reativação, então mais uma falha pode desativá-lo de novo (issue aberta woocommerce#70247).
O que o plugin monitora
A desativação
Escuta a ação do próprio WooCommercewoocommerce_webhook_disabled_due_delivery_failures e registra um episódio por desativação.Uma tentativa de notificação por episódio
O plugin tenta enviar uma notificação por episódio. Sinais repetidos do mesmo episódio são contados no painel e não geram nova tentativa. A deduplicação usa chave única no banco (testada com dois processos simultâneos em SQLite e MariaDB).Orientação para restaurar
Uma página no painel lista cada episódio com tópico, número de falhas, último código de resposta, diagnóstico em linguagem simples e os passos manuais para restaurar a entrega.Como o administrador é avisado
O plugin mostra um aviso no painel e tenta enviar um e-mail de notificação por episódio ao endereço de administrador do site, via wp_mail() do WordPress. Chegar à caixa de entrada depende da configuração de e-mail do seu site. O e-mail identifica o webhook só por ID e tópico, porque o nome é texto livre e pode conter dados sensíveis. Exemplo do formato da v0.3.1 (valores ilustrativos; o e-mail do plugin é em inglês e traduzível; linhas finais abreviadas):
Subject: [Your Store] WooCommerce disabled webhook #12 (order.created) after repeated delivery failures WooCommerce automatically disabled a webhook because its deliveries kept failing. No further events for this topic will be sent until it is reactivated. Webhook ID: 12 (the name is not included in this e-mail; see WooCommerce > Settings > Advanced > Webhooks) Topic: order.created Delivery endpoint (scheme, host and port only; host may be redacted): https://[host redacted] Failure count: 6 (threshold 5) Last response: 503 (illustrative) Disabled at (UTC): 2026-11-11 02:04:16 Diagnosis: ... How to restore delivery: 1. Fix the receiving endpoint first ... 4. Events that happened while the webhook was disabled were not delivered and are not queued. ... This plugin attempts at most one notification per disable episode. Further failed-delivery signals for the same episode are counted on the details page and do not trigger another attempt. If processing stops before the mail attempt completes, the status may remain Pending. Notifications are not automatically retried. (other lines abbreviated)
Status do e-mail no painel (rótulos em inglês no plugin)
| Status | Significado |
|---|---|
| Accepted by WordPress (aceito pelo WordPress) | wp_mail() retornou sucesso: a mensagem foi repassada ao sistema de e-mail do seu site. Isso não confirma a chegada à caixa de entrada. |
| Failed (falhou) | wp_mail() retornou falso ou registrou erro. Fica só um código genérico (ex.: wp_mail_failed), nunca o texto do erro, que pode conter endereços. |
| Pending (pendente) | O episódio foi registrado, mas a tentativa não terminou, ou o PHP parou no meio. Não há nova tentativa. |
| Captured locally (not sent) (capturado localmente) | Só em ambiente de teste, com a constante WDMFW_CAPTURE_MAIL definida. Nada foi enviado. |
| Not sent: no valid recipient (sem destinatário válido) | Não havia endereço de destinatário válido, então nenhum e-mail foi tentado. |
Nenhum status significa "entregue". O plugin não recebe confirmação de nenhum provedor de e-mail.
O que o plugin não faz
- Não reativa, edita, reenvia nem refaz (replay) webhooks.
- Não recupera eventos perdidos enquanto o webhook esteve desativado.
- Não impede falhas de entrega nem mantém ativo um webhook que falha.
- Não garante a entrega do e-mail de alerta.
- Não testa seu endpoint, não altera o
failure_counte não se comunica com nenhum serviço externo.
Se você precisa de novas tentativas automáticas, log com payloads ou replay, use um plugin de camada de entrega ou um gateway de webhooks hospedado. Este plugin é somente leitura de propósito.
O que é armazenado e o que pode continuar visível
| Armazenado pelo plugin (no banco do seu próprio WordPress) | Não armazenado pelo plugin |
|---|---|
| ID do webhook, tópico, número de falhas, limite, último código de resposta, datas, estado do episódio, status do e-mail e um código genérico de falha. O endpoint reduzido a esquema://host:porta, em que o host pode aparecer como [host redacted]. |
O nome do webhook (não é armazenado, exibido nem enviado por e-mail; o plugin usa Webhook #ID e o tópico). Dados de pedidos ou clientes e payloads. Caminho, query string, fragmento, usuário e senha da URL: são descartados antes de qualquer gravação. |
Como o host é tratado
O plugin não tenta detectar segredos, e nenhuma regra reconhece todos os segredos. Ele usa uma lista de permissão. O host só é mantido se for:
- o próprio domínio registrável (ex.:
example.com,loja.com.br); - o domínio registrável com exatamente um destes rótulos na frente:
www,api,hook,hooks,webhook,webhooks; - um host de automação da lista permitida (Zapier e Make por padrão; o dono do site pode ampliar por filtro);
localhost, ou um IP privado, de loopback ou reservado.
Todo o resto, incluindo outros subdomínios e qualquer IP público, vira [host redacted]. A porta é mantida.
O que pode continuar visível
- O domínio registrável, um rótulo seguro ou um host da lista permitida. Se o próprio domínio for sensível (ex.: um domínio aleatório comprado para uma integração), ele continua visível.
- IPs privados, de loopback e reservados, e a porta.
- Fora do controle do plugin: o log
webhooks-deliverye a tabela de webhooks do próprio WooCommerce guardam a URL completa e o nome do webhook.
Nada é enviado para nós nem para terceiros. A única mensagem que sai é o e-mail de notificação enviado pelo seu próprio site via wp_mail().
Limitações atuais
- Reativação direta no banco: se o webhook for reativado direto no banco (sem hook do WordPress) e desativado de novo sem nenhuma entrega no meio, a nova desativação pode ser tratada como repetição e não gerar e-mail.
- Janela de 300 segundos: reativação sem hook seguida de nova desativação em menos de 300 s é contada como repetição, de propósito, para evitar e-mail duplicado em corridas.
- Possível perda de e-mail: se o PHP cair entre o registro do episódio e o fim da chamada a
wp_mail(), o e-mail não é reenviado (fica Pendente). O episódio continua no painel. - Sem replay dos eventos perdidos.
- Sem garantia de entrega do e-mail de alerta.
- Testado apenas em (v0.3.0; a v0.3.1 só muda o texto do e-mail, e a geração do e-mail foi retestada em PHP 8.4, WooCommerce 11.2.2, SQLite e MariaDB 11.4): WordPress 7.1.4 com PHP 8.4 em SQLite e MariaDB 11.4, WooCommerce 11.2.2 e 11.3.0-rc.2, HPOS ligado e desligado; PHP 8.1 só com WooCommerce 11.2.2 e HPOS ligado. MySQL, multisite, cache de objetos, PHP 8.2/8.3 e outras versões não foram testados.
A versão premium está em avaliação
O plugin acima será gratuito. Estamos avaliando se um complemento pago seria útil o bastante para ser construído. Nada está à venda: não há checkout nem pré-venda. Veja as ideias de preço em avaliação (em inglês).