Pruebe los webhooks de WooCommerce en Localhost

Para probar los webhooks de WooCommerce en localhost, exponga su controlador local con un túnel HTTPS, cree un webhook en WooCommerce → Configuración → Avanzado → Webhooks y verifique X-WC-Webhook-Signature como un resumen Base64 HMAC-SHA256 del cuerpo crudo. Active un pedido o cambio de producto en una tienda de prueba segura, inspeccione la entrega y repita sin implementar el receptor.

Qué envía WooCommerce y cuándo

WooCommerce puede notificar a una URL de entrega cuando se crean, actualizan o eliminan pedidos, productos, cupones o clientes. Las extensiones pueden agregar temas y los desarrolladores pueden definir temas personalizados. Cada webhook configurado tiene un nombre, estado, tema, URL de entrega, secreto y versión de API. El documentación oficial del webhook de WooCommerce describe la creación, los temas, los registros de entrega y el comportamiento de falla.

Un webhook se adjunta automáticamente a un tema, no a cada mutación de la tienda. Elija el tema más específico que su integración necesita. Un consumidor creado por un pedido no debería procesar también todas las actualizaciones del producto. Esto reduce la exposición de datos personales, el tráfico y los efectos secundarios accidentales durante las pruebas locales.

Crear un punto final Express de cuerpo sin formato

La firma de WooCommerce se calcula sobre el cuerpo que envía. Conserve esos bytes hasta que se complete la verificación. El encabezado de la firma contiene el resumen binario HMAC-SHA256 codificado en Base64, no una cadena 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);

El analizador sin formato específico de la ruta debe ejecutarse antes que un analizador JSON global. Si el middleware analiza el cuerpo primero, volver a encadenar el objeto puede cambiar los espacios en blanco o escapar e invalidar el resumen. Esta es la misma regla del cuerpo crudo cubierta en el guía de firma de webhook, pero WooCommerce usa específicamente salida Base64.

Iniciar el túnel HTTPS

1. Inicie su receptor y confirme que escucha http://localhost:3000.
2. Correr npx portpreview 3000 en una segunda terminal.
3. Copie la URL HTTPS pública y añádala /webhooks/woocommerce.
4. Mantenga el proceso en ejecución mientras WordPress envía su ping inicial y las entregas de temas.

El host de WordPress, no el navegador donde abrió wp-admin, debe poder acceder a la URL pública. Un túnel une esa solicitud pública con su proceso de desarrollo privado. También proporciona TLS confiable, por lo que no es necesario exponer un puerto de enrutador ni instalar su propio certificado público.

Configurar el webhook en WooCommerce

1. Abierto WooCommerce → Configuración → Avanzado → Webhooks.
2. Seleccionar Agregar webhook y darle un nombre reconocible de desarrollo local.
3. Elegir Activo estado y un tema específico, como Pedido creado.
4. Pegue la URL de entrega del túnel completa.
5. Genere un secreto aleatorio largo y coloque el valor idéntico en WC_WEBHOOK_SECRET.
6. Guarde el webhook y luego active el tema en una tienda de prueba.

Cuando se guarda un webhook activo por primera vez, WooCommerce envía un ping a la URL de entrega. El ping confirma la conectividad, pero no sustituye la carga útil de un pedido real. Haga que su terminal tolere la solicitud inicial y luego cree o actualice datos de prueba para ejercitar el tema seleccionado.

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

Si pega un secreto Base64 en un archivo de entorno, cítelo para conservar la puntuación. El secreto es la clave HMAC; Las claves de consumidor de la API REST de WooCommerce y las contraseñas de WordPress son credenciales no relacionadas.

Utilice encabezados para enrutar y rastrear entregas

WooCommerce incluye encabezados de metadatos útiles. Según la versión y el entorno, estos incluyen el tema, el recurso, el evento, la fuente, el ID del webhook y el ID de entrega. Trate los nombres sin distinguir entre mayúsculas y minúsculas como lo requiere HTTP. Utilice el tema de envío y el ID de entrega para la trazabilidad, pero siempre autentique el cuerpo primero.

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

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

No infieras el tema únicamente a partir de la forma JSON. La carga útil de una orden creada y una orden actualizada pueden tener un aspecto similar, mientras que la acción posterior correcta difiere. Por el contrario, rechace una combinación de encabezado/tema que su terminal nunca estuvo configurado para aceptar.

Procesar cargas útiles de pedidos de forma defensiva

Utilice identificadores inmutables

Correlacione registros por identidad de tienda e ID de objeto de WooCommerce, no por formato de número de pedido, correo electrónico del cliente o nombres para mostrar. Dos tiendas pueden tener el ID de pedido 42, por lo que las integraciones de varias tiendas necesitan una clave compuesta.

Espere que las extensiones alteren los campos

Las extensiones de pago, suscripción, impuestos, pago y cumplimiento pueden agregar metadatos y campos de elementos de línea. Valide los campos que requiere su lógica de negocios, ignore los campos desconocidos y guarde una versión de esquema o un elemento mínimo redactado para pruebas de regresión.

Separe el recibo del evento del cumplimiento

Un webhook que indique que se ha modificado un pedido debe entrar en una cola o bandeja de entrada duradera. La sincronización del inventario, las etiquetas de envío, las llamadas al ERP y el correo electrónico del cliente deben ejecutarse después del acuse de recibo. Esto evita que una dependencia lenta haga que WooCommerce interprete un recibo exitoso como una entrega fallida.

Actualizaciones de modelos como transiciones de estado.

Un pedido puede pasar por estados pendientes, en procesamiento, en espera, completados, cancelados, reembolsados ​​o fallidos. Las actualizaciones pueden ocurrir rápidamente y el pedido de entrega no es un sustituto seguro para comparar marcas de tiempo y el estado actual de la fuente. Haga que las transiciones repetidas sean inofensivas.

La idempotencia es obligatoria para eventos comerciales.

Puede ocurrir un tiempo de espera después de que el receptor se confirma pero antes de que WooCommerce vea la respuesta. La nueva entrega produce entonces la misma acción comercial a menos que el controlador sea idempotente. Guarde el ID de entrega donde esté presente. También aplique la unicidad a nivel de dominio, como una solicitud de cumplimiento por tienda y transición de pedidos.

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);
});

Una transacción de bandeja de entrada más bandeja de salida evita tanto el manejo duplicado como la pérdida de trabajo de seguimiento. Ver reintento de webhook e idempotencia para el patrón completo.

Utilice registros de WooCommerce para depurar el lado del remitente

WooCommerce registra las entregas de webhooks. Abierto WooCommerce → Estado → Registros y filtrar por la fuente de entrega del webhook descrita en la documentación oficial. Compare la URL de entrega, la hora de la solicitud, el estado de la respuesta y el cuerpo de la respuesta con el seguimiento de su túnel local. Los registros del remitente responden si WordPress intentó realizar la solicitud; Los registros del receptor responden lo que hizo su aplicación con él.

No copie la carga útil de un pedido sin editar en una edición pública. Puede contener nombres, direcciones de facturación y envío, correo electrónico, teléfono, selecciones de productos y metadatos de pago. Reduzca el dispositivo a los campos necesarios para reproducir el error.

Solucionar fallas comunes del webhook de WooCommerce

El webhook queda deshabilitado

WooCommerce desactiva automáticamente un webhook después de más de cinco errores de entrega consecutivos. Las respuestas fuera de 2xx, 301 o 302 cuentan como fallas según la guía oficial. Arregle el punto final, reactive el webhook y envíe una prueba controlada. Evite las redirecciones de todos modos: complican la depuración de firmas y pueden enviar accidentalmente datos firmados del cliente a un host no deseado.

La firma siempre difiere.

Haga un hash del cuerpo sin formato exacto con el secreto configurado del webhook, solicite una salida HMAC binaria y luego codifique en Base64. En Node, eso es .digest('base64'). Los errores comunes son usar hexadecimal, usar un secreto de API REST, analizar JSON primero o incluir bytes de nueva línea adicionales.

El ping inicial funciona pero los eventos de orden no.

Confirme que el tema seleccionado coincida con la acción que desencadenó. Crear un pedido y cambiar un pedido existente son temas diferentes. Verifique que el estado sea Activo, verifique los registros de WooCommerce y asegúrese de que un complemento o un caché provisional no impida el enlace subyacente.

Las solicitudes locales devuelven 404

Verifique la ruta completa, el método de ruta y el puerto de destino del túnel. WordPress debe PUBLICAR en /webhooks/woocommerce, no simplemente el origen del túnel. El middleware del marco no debe redirigir el webhook a una página localizada o autenticada.

Se agotó el tiempo de entrega

Conserve el evento autenticado y devuelva 200 o 202 lo antes posible. Traslade llamadas API remotas y transformaciones pesadas a un trabajador. Compruebe si los puntos de interrupción locales pausan la solicitud el tiempo suficiente para clasificarla como un error.

Reproducir una carga útil provoca un 401

Una solicitud capturada debe conservar los bytes sin procesar exactos y el encabezado de firma. La edición de JSON invalida la firma original. Para pruebas de lógica empresarial, utilice un dispositivo desinfectado después del límite de verificación; para pruebas de un extremo a otro, genere un nuevo HMAC con un secreto de prueba dedicado. Sigue el flujo de trabajo de reproducción seguro.

Lista de verificación de seguridad para los datos de la tienda local

• Pruebe en una tienda de ensayo con clientes y productos sintéticos siempre que sea posible.
• Utilice un secreto de webhook único para el desarrollo local y rótelo después de su exposición.
• Verifique la firma antes de analizar, registrar o poner en cola el cuerpo.
• Incluya en la lista de permitidos el origen y el tema de la tienda esperados después de la verificación criptográfica.
• Redactar direcciones, detalles de contacto, notas de pedidos y metadatos de pago de las capturas.
• Nunca deshabilite la verificación TLS ni exponga las credenciales de wp-admin al receptor.

La arquitectura local debe coincidir con la producción: transporte HTTPS, autenticación de cuerpo sin formato, aceptación duradera, procesamiento idempotente, respuesta rápida y fallas auditables. Para otro proveedor comercial con un encabezado HMAC diferente, compare el Guía de webhooks locales de Shopify.