Webhooks de WooCommerce que fallan: cómo diagnosticarlos

Síntomas

• El sistema receptor no recibe algunos eventos, o ninguno.
• Los eventos llegan con minutos u horas de retraso.
• El estado del webhook ha pasado a Desactivado sin que nadie lo tocara.
• El receptor procesa el mismo pedido dos veces.
• El receptor rechaza las entregas por no estar autenticadas.

Causas más comunes

1. El receptor falla: devuelve 4xx/5xx por sus propios fallos, sus reglas de autenticación o su validación de payloads inesperados.
2. El receptor es demasiado lento: hace todo su trabajo antes de responder y la petición supera el tiempo.
3. Algo bloquea la entrega: el firewall, el WAF o la lista de IPs permitidas del receptor; o el hosting de la tienda bloquea las peticiones salientes.
4. La verificación de la firma está mal hecha: calculada sobre el JSON ya interpretado en lugar del cuerpo bruto, o con un secreto antiguo.
5. El procesamiento en segundo plano está atascado: Action Scheduler o WP-Cron no se ejecutan, y las entregas se acumulan.
6. Los receptores no son idempotentes: order.updated se dispara en muchos guardados y los reintentos reenvían eventos, así que el mismo pedido llega varias veces.

Diagnóstico

1. Revisa el estado y los registros de entrega

En WooCommerce → Ajustes → Avanzado → Webhooks, revisa el estado (Activo, En pausa, Desactivado), el tema y la URL de entrega. Después busca en WooCommerce → Estado → Registros el registro de entregas de webhooks, que anota cada entrega con su código de respuesta y su duración.

2. Revisa la cola

Las entregas se ejecutan como acciones woocommerce_deliver_webhook_async. En Herramientas → Acciones programadas, busca ese hook: muchas acciones Pendientes o con fecha pasada significan que la cola no se procesa; las acciones Fallidas contienen el error.

3. Revisa el receptor

En el lado receptor, registra la petición bruta, las cabeceras y la respuesta que devuelve para una entrega de prueba. WooCommerce envía cabeceras útiles: X-WC-Webhook-Topic, X-WC-Webhook-Resource, X-WC-Webhook-ID, X-WC-Webhook-Delivery-ID y X-WC-Webhook-Signature.

Registros y comprobaciones técnicas

• Ajustes del webhook: estado, tema, URL de entrega, secreto, versión de la API.
• Registros de WooCommerce para las entregas de webhooks.
• Herramientas → Acciones programadas: acciones de entrega pendientes, vencidas y fallidas.
• Registros del receptor: cuerpo bruto, cabeceras, código de respuesta, tiempo de procesamiento.
• Firewalls en ambos lados: peticiones salientes desde la tienda, entrantes en el receptor.

Soluciones

• Responde rápido, procesa después: el receptor debe verificar la firma, guardar el evento y devolver 200 inmediatamente, y procesarlo luego en su propia cola.
• Verifica las firmas sobre el cuerpo bruto:

$payload   = file_get_contents( 'php://input' );
$signature = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? '';
$expected  = base64_encode( hash_hmac( 'sha256', $payload, WEBHOOK_SECRET, true ) );

if ( ! hash_equals( $expected, $signature ) ) {
    http_response_code( 401 );
    exit;
}

// Guarda el evento, devuelve 200 ya y procésalo de forma asíncrona.

• Acepta el ping que WooCommerce envía al guardar un webhook (datos de formulario con webhook_id) y devuelve 200.
• Haz el procesamiento idempotente: usa el ID de entrega y el ID del recurso junto con su fecha de modificación para omitir los eventos ya aplicados.
• Mantén la cola en marcha: asegúrate de que WP-Cron se ejecuta, preferiblemente desde un cron real del servidor, y vacía cualquier acumulación de Action Scheduler.
• Reactiva el webhook tras arreglar el receptor: vuelve a ponerlo en Activo.

Qué no hacer

• No te saltes la verificación de la firma en el receptor; cualquiera podría enviarle pedidos falsos.
• No ejecutes trabajo lento (llamadas al ERP, emails, generación de PDF) antes de responder al webhook.
• No reactives una y otra vez un webhook desactivado sin arreglar el receptor; volverá a desactivarse.
• No borres acciones de entrega pendientes para «limpiar»: son eventos que el receptor aún no ha visto.

Cuándo recurrir a un experto

Recurre a un ingeniero cuando la integración pierde o duplica pedidos, cuando solo controlas un lado de la integración y necesitas evidencias para el otro, o cuando hay que reconstruir el receptor para que sea rápido, verificado e idempotente.

Problemas relacionados

• WooCommerce / Rendimiento Problemas con Action Scheduler en WooCommerce Acciones programadas vencidas, fallidas y atascadas: cómo funciona la cola, por qué se detiene y cómo arreglarlo sin perder trabajo pendiente. →
• WooCommerce / Integraciones Errores de la REST API de WooCommerce: cómo diagnosticarlos Lee el código de estado y el código de error de la respuesta: autenticación, permisos, rutas, capas de seguridad y errores del servidor fallan cada uno de una forma. →
• WooCommerce / Pagos WooCommerce: el pago falla pero al cliente se le ha cobrado Cuando la pasarela cobra el pago pero el pedido se queda pendiente o fallido, revisa el traspaso de callbacks y webhooks antes de tocar el pedido. →

Preguntas frecuentes