Teste Webhooks WooCommerce no Localhost

Para testar webhooks WooCommerce em localhost, exponha seu manipulador local com um túnel HTTPS, crie um webhook em WooCommerce → Configurações → Avançado → Webhooks e verifique X-WC-Webhook-Signature como um resumo Base64 HMAC-SHA256 do corpo bruto. Acione um pedido ou alteração de produto em uma loja de teste segura, inspecione a entrega e repita sem implantar o receptor.

O que o WooCommerce envia e quando

WooCommerce pode notificar um URL de entrega quando pedidos, produtos, cupons ou clientes são criados, atualizados ou excluídos. As extensões podem adicionar tópicos e os desenvolvedores podem definir tópicos personalizados. Cada webhook configurado possui nome, status, tópico, URL de entrega, segredo e versão da API. O documentação oficial do webhook do WooCommerce descreve criação, tópicos, logs de entrega e comportamento de falha.

Um webhook é anexado a um tópico, não a cada mutação de loja automaticamente. Escolha o tópico mais restrito que sua integração precisa. Um consumidor criado por pedido também não deve processar todas as atualizações do produto. Isso reduz a exposição de dados pessoais, o tráfego e os efeitos colaterais acidentais durante os testes locais.

Crie um endpoint Express de corpo bruto

A assinatura do WooCommerce é calculada sobre o corpo que ele envia. Preserve esses bytes até que a verificação seja concluída. O cabeçalho da assinatura contém o resumo HMAC-SHA256 binário codificado em Base64, não uma string hexadecimal.

import express from 'express';
import crypto from 'node:crypto';

const app = express();

function validWooSignature(rawBody, supplied, secret) {
  if (!supplied || !secret) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('base64');
  const a = Buffer.from(supplied);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post(
  '/webhooks/woocommerce',
  express.raw({ type: 'application/json', limit: '2mb' }),
  async (req, res) => {
    const supplied = req.get('x-wc-webhook-signature');
    if (!validWooSignature(req.body, supplied, process.env.WC_WEBHOOK_SECRET)) {
      return res.sendStatus(401);
    }

    const payload = JSON.parse(req.body.toString('utf8'));
    await webhookInbox.insertOnce({
      deliveryId: req.get('x-wc-webhook-delivery-id'),
      topic: req.get('x-wc-webhook-topic'),
      payload,
    });
    return res.sendStatus(202);
  },
);

app.use(express.json());
app.listen(3000);

O analisador bruto específico da rota deve ser executado antes de um analisador JSON global. Se o middleware analisar o corpo primeiro, a restringificação do objeto poderá alterar os espaços em branco ou o escape e invalidar o resumo. Esta é a mesma regra do corpo bruto abordada no guia de assinatura do webhook, mas o WooCommerce usa especificamente saída Base64.

Inicie o túnel HTTPS

1. Ligue o seu receptor e confirme se ele escuta http://localhost:3000.
2. Correr npx portpreview 3000 em um segundo terminal.
3. Copie o URL HTTPS público e anexe /webhooks/woocommerce.
4. Mantenha o processo em execução enquanto o WordPress envia seu ping inicial e entregas de tópicos.

O host do WordPress – e não o navegador onde você abriu o wp-admin – deve ser capaz de acessar o URL público. Um túnel conecta essa solicitação pública ao seu processo de desenvolvimento privado. Ele também fornece TLS confiável, para que você não precise expor uma porta de roteador ou instalar seu próprio certificado público.

Configure o webhook no WooCommerce

1. Abrir WooCommerce → Configurações → Avançado → Webhooks.
2. Selecione Adicionar webhook e dar-lhe um nome reconhecível de desenvolvimento local.
3. Escolher Ativo status e um tópico específico, como Pedido criado.
4. Cole o URL completo de entrega do túnel.
5. Gere um segredo aleatório longo e coloque o valor idêntico em WC_WEBHOOK_SECRET.
6. Salve o webhook e acione o tópico em um armazenamento de teste.

Quando um webhook ativo é salvo pela primeira vez, o WooCommerce envia um ping para o URL de entrega. O ping confirma a conectividade, mas não substitui uma carga útil de pedido real. Faça com que seu endpoint tolere a solicitação inicial e, em seguida, crie ou atualize dados de teste para exercitar o tópico selecionado.

export WC_WEBHOOK_SECRET="$(openssl rand -base64 48)"

Se você colar um segredo Base64 em um arquivo de ambiente, coloque-o entre aspas para que a pontuação seja preservada. O segredo é a chave HMAC; As chaves do consumidor da API REST do WooCommerce e as senhas do WordPress são credenciais não relacionadas.

Use cabeçalhos para rotear e rastrear entregas

WooCommerce inclui cabeçalhos de metadados úteis. Dependendo da versão e do ambiente, eles incluem o tópico, o recurso, o evento, a origem, o ID do webhook e o ID de entrega. Trate os nomes sem distinção entre maiúsculas e minúsculas, conforme exigido pelo HTTP. Utilize o tópico para expedição e o ID de entrega para rastreabilidade, mas sempre autentique primeiro o corpo.

const handlers = {
  'order.created': handleOrderCreated,
  'order.updated': handleOrderUpdated,
  'product.updated': handleProductUpdated,
};

const handler = handlers[topic];
if (handler) await handler(payload);
else await recordUnsupportedTopic(topic);

Não infira o tópico apenas a partir da forma JSON. Uma carga útil de pedido criado e atualizada pode ser semelhante, enquanto a ação downstream correta é diferente. Por outro lado, rejeite uma combinação de cabeçalho/tópico que seu endpoint nunca foi configurado para aceitar.

Processar cargas úteis de pedidos defensivamente

Use identificadores imutáveis

Correlacione registros por identidade da loja e ID do objeto WooCommerce, não pela formatação do número do pedido, e-mail do cliente ou nomes de exibição. Duas lojas podem ter o ID de pedido 42, portanto, as integrações de várias lojas precisam de uma chave composta.

Espere que as extensões alterem os campos

Extensões de pagamento, assinatura, impostos, checkout e atendimento podem adicionar metadados e campos de item de linha. Valide os campos exigidos pela sua lógica de negócios, ignore campos desconhecidos e salve uma versão do esquema ou um acessório editado mínimo para testes de regressão.

Separe o recebimento do evento do cumprimento

Um webhook informando que um pedido foi alterado deve entrar em uma fila ou caixa de entrada durável. A sincronização de estoque, etiquetas de envio, chamadas de ERP e e-mail do cliente devem ser executadas após a confirmação. Isso evita que uma dependência lenta faça o WooCommerce interpretar um recebimento bem-sucedido como uma falha na entrega.

Atualizações de modelo como transições de estado

Um pedido pode passar por estados pendentes, em processamento, em espera, concluídos, cancelados, reembolsados ​​ou com falha. As atualizações podem ocorrer rapidamente e a ordem de entrega não é um substituto seguro para comparar carimbos de data/hora e estado de origem atual. Torne as transições repetidas inofensivas.

A idempotência é obrigatória para eventos comerciais

Um tempo limite pode ocorrer após o destinatário confirmar, mas antes que o WooCommerce veja a resposta. A reentrega produz então a mesma ação comercial, a menos que o manipulador seja idempotente. Armazene o ID de entrega onde estiver presente. Imponha também a exclusividade no nível do domínio, como uma solicitação de atendimento por loja e transição de pedido.

await db.transaction(async (tx) => {
  if (!(await tx.deliveries.claim(deliveryId))) return;
  await tx.orders.applyWooCommerceEvent(storeId, topic, payload);
  await tx.outbox.enqueueRequiredActions(storeId, topic, payload.id);
});

Uma transação de caixa de entrada mais caixa de saída evita o manuseio duplicado e a perda de trabalho de acompanhamento. Ver nova tentativa e idempotência do webhook para o padrão completo.

Use logs do WooCommerce para depurar o lado do remetente

WooCommerce registra entregas de webhook. Abrir WooCommerce → Status → Registros e filtre a fonte de entrega do webhook descrita na documentação oficial. Compare o URL de entrega, o tempo de solicitação, o status da resposta e o corpo da resposta com o rastreamento do túnel local. Os logs do remetente respondem se o WordPress tentou a solicitação; os logs do receptor respondem ao que seu aplicativo fez com ele.

Não copie uma carga útil de pedido não editada em um problema público. Ele pode conter nomes, endereços de cobrança e entrega, e-mail, telefone, seleções de produtos e metadados de pagamento. Reduza o fixture aos campos necessários para reproduzir o bug.

Solucionar problemas comuns de falhas do webhook do WooCommerce

O webhook fica desativado

WooCommerce desativa automaticamente um webhook após mais de cinco falhas consecutivas de entrega. Respostas fora de 2xx, 301 ou 302 contam como falhas de acordo com o guia oficial. Corrija o endpoint, reative o webhook e envie um teste controlado. Evite redirecionamentos de qualquer maneira: eles complicam a depuração de assinaturas e podem enviar acidentalmente dados assinados do cliente para um host não intencional.

A assinatura sempre difere

Faça hash do corpo bruto exato com o segredo configurado do webhook, solicite a saída HMAC binária e codifique-a em Base64. No Node, isso é .digest('base64'). Erros comuns são usar hexadecimal, usar um segredo da API REST, analisar JSON primeiro ou incluir bytes de nova linha extras.

O ping inicial funciona, mas os eventos de pedido não

Confirme se o tópico selecionado corresponde à ação que você acionou. Criar um pedido e alterar um pedido existente são tópicos diferentes. Verifique se o status está ativo, verifique os logs do WooCommerce e certifique-se de que um plug-in ou cache de teste não esteja impedindo o gancho subjacente.

Solicitações locais retornam 404

Verifique o caminho completo, o método de rota e a porta de destino do túnel. WordPress deve POSTAR para /webhooks/woocommerce, não apenas a origem do túnel. O middleware da estrutura não deve redirecionar o webhook para uma página localizada ou autenticada.

Tempo limite de entregas

Persista o evento autenticado e retorne 200 ou 202 imediatamente. Mova chamadas remotas de API e transformações pesadas para um trabalhador. Verifique se os pontos de interrupção locais pausam a solicitação por tempo suficiente para serem classificados como uma falha.

Reproduzir uma carga causa um 401

Uma solicitação capturada deve reter os bytes brutos exatos e o cabeçalho da assinatura. A edição do JSON invalida a assinatura original. Para testes de lógica de negócios, use um acessório higienizado após o limite de verificação; para testes ponta a ponta, gere um novo HMAC com um segredo de teste dedicado. Siga o fluxo de trabalho de reprodução seguro.

Lista de verificação de segurança para dados de armazenamento local

• Teste em uma loja intermediária com clientes e produtos sintéticos sempre que possível.
• Use um segredo de webhook exclusivo para desenvolvimento local e alterne-o após a exposição.
• Verifique a assinatura antes de analisar, registrar ou enfileirar o corpo.
• Coloque na lista de permissões a origem e o tópico esperados do armazenamento após a verificação criptográfica.
• Edite endereços, detalhes de contato, notas de pedidos e metadados de pagamento de capturas.
• Nunca desative a verificação TLS ou exponha as credenciais wp-admin ao destinatário.

A arquitetura local deve corresponder à produção: transporte HTTPS, autenticação bruta, aceitação durável, processamento idempotente, resposta rápida e falhas auditáveis. Para outro provedor de comércio com um cabeçalho HMAC diferente, compare o Guia de webhook local do Shopify.