Webhooks de WooCommerce que fallen: com diagnosticar-los

Símptomes

• El sistema receptor no rep alguns esdeveniments, o cap.
• Els esdeveniments arriben amb minuts o hores de retard.
• L’estat del webhook ha passat a Desactivat sense que ningú el toqués.
• El receptor processa la mateixa comanda dues vegades.
• El receptor rebutja els lliuraments perquè no estan autenticats.

Causes més habituals

1. El receptor falla: retorna 4xx/5xx per les seves pròpies fallades, les seves regles d’autenticació o la seva validació de payloads inesperats.
2. El receptor és massa lent: fa tota la feina abans de respondre i la petició supera el temps.
3. Alguna cosa bloqueja el lliurament: el tallafoc, el WAF o la llista d’IPs permeses del receptor; o el hosting de la botiga bloqueja les peticions sortints.
4. La verificació de la signatura està mal feta: calculada sobre el JSON ja interpretat en lloc del cos en brut, o amb un secret antic.
5. El processament en segon pla està encallat: Action Scheduler o WP-Cron no s’executen, i els lliuraments s’acumulen.
6. Els receptors no són idempotents: order.updated es dispara en molts desaments i els reintents reenvien esdeveniments, així que la mateixa comanda arriba diverses vegades.

Diagnosi

1. Revisa l’estat i els registres de lliurament

A WooCommerce → Paràmetres → Avançat → Webhooks, revisa l’estat (Actiu, En pausa, Desactivat), el tema i la URL de lliurament. Després busca a WooCommerce → Estat → Registres el registre de lliuraments de webhooks, que anota cada lliurament amb el seu codi de resposta i la seva durada.

2. Revisa la cua

Els lliuraments s’executen com a accions woocommerce_deliver_webhook_async. A Eines → Accions programades, busca aquest hook: moltes accions Pendents o amb data passada volen dir que la cua no es processa; les accions Fallides contenen l’error.

3. Revisa el receptor

Al costat receptor, registra la petició en brut, les capçaleres i la resposta que retorna per a un lliurament de prova. WooCommerce envia capçaleres útils: X-WC-Webhook-Topic, X-WC-Webhook-Resource, X-WC-Webhook-ID, X-WC-Webhook-Delivery-ID i X-WC-Webhook-Signature.

Registres i comprovacions tècniques

• Paràmetres del webhook: estat, tema, URL de lliurament, secret, versió de l’API.
• Registres de WooCommerce per als lliuraments de webhooks.
• Eines → Accions programades: accions de lliurament pendents, vençudes i fallides.
• Registres del receptor: cos en brut, capçaleres, codi de resposta, temps de processament.
• Tallafocs als dos costats: peticions sortints des de la botiga, entrants al receptor.

Solucions

• Respon ràpid, processa després: el receptor ha de verificar la signatura, desar l’esdeveniment i retornar 200 immediatament, i processar-lo després a la seva pròpia cua.
• Verifica les signatures sobre el cos en brut:

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

// Desa l’esdeveniment, retorna 200 ara i processa’l de manera asíncrona.

• Accepta el ping que WooCommerce envia en desar un webhook (dades de formulari amb webhook_id) i retorna 200.
• Fes el processament idempotent: fes servir l’ID de lliurament i l’ID del recurs juntament amb la seva data de modificació per ometre els esdeveniments ja aplicats.
• Mantén la cua en marxa: assegura’t que WP-Cron s’executa, preferiblement des d’un cron real del servidor, i buida qualsevol acumulació d’Action Scheduler.
• Reactiva el webhook després d’arreglar el receptor: torna’l a posar a Actiu.

Què no s’ha de fer

• No et saltis la verificació de la signatura al receptor; qualsevol li podria enviar comandes falses.
• No executis feina lenta (crides a l’ERP, correus, generació de PDF) abans de respondre al webhook.
• No reactivis una vegada i una altra un webhook desactivat sense arreglar el receptor; es tornarà a desactivar.
• No esborris accions de lliurament pendents per «netejar»: són esdeveniments que el receptor encara no ha vist.

Quan recórrer a un expert

Recorre a un enginyer quan la integració perd o duplica comandes, quan només controles un costat de la integració i necessites evidències per a l’altre, o quan cal reconstruir el receptor perquè sigui ràpid, verificat i idempotent.

Problemes relacionats

• WooCommerce / Rendiment Problemes amb Action Scheduler a WooCommerce Accions programades vençudes, fallides i encallades: com funciona la cua, per què s’atura i com arreglar-ho sense perdre feina pendent. →
• WooCommerce / Integracions Errors de la REST API de WooCommerce: com diagnosticar-los Llegeix el codi d’estat i el codi d’error de la resposta: autenticació, permisos, rutes, capes de seguretat i errors del servidor fallen cadascun d’una manera. →
• WooCommerce / Pagaments WooCommerce: el pagament falla però al client se li ha cobrat Quan la passarel·la cobra el pagament però la comanda queda pendent o fallida, revisa el traspàs de callbacks i webhooks abans de tocar la comanda. →

Preguntes freqüents