wp cron event run rejoue une synchronisation headless restée bloquée

Trois jours sans le moindre changement visible côté front, alors que deux articles ont pourtant été publiés sur le back-office WordPress entre-temps. Le rebuild statique censé suivre chaque publication n’a tout simplement pas eu lieu, et personne n’a touché à la configuration du serveur.

Ce genre de silence a presque toujours la même origine dans une architecture headless : une tâche planifiée qui ne s’est jamais exécutée. WordPress ne dispose pas d’un vrai cron système par défaut ; il simule cette mécanique à chaque chargement de page, ce qui devient fragile dès qu’un site reçoit peu de visites ou qu’un webhook de build a été raccroché à un hook mal choisi.

Symptôme : un déclencheur qui reste muet

Le scénario typique ressemble à ceci : une extension maison écoute save_post pour notifier un service de build externe, mais la notification part uniquement si une tâche cron intermédiaire s’exécute pour agréger plusieurs modifications avant de déclencher l’appel. Si cette tâche ne tourne pas, l’appel HTTP vers le service de build n’est jamais émis, et le front continue d’afficher une version périmée du contenu.

Le premier réflexe consiste souvent à vérifier les journaux du service de build lui-même, ce qui est une perte de temps : le problème se situe en amont, côté WordPress, avant même que la requête sortante soit tentée.

Diagnostic : interroger la file avec WP-CLI

La commande wp cron event list affiche l’état complet de la file cron, avec pour chaque évènement son nom de hook, l’heure prévue et le statut. Une tâche affichée avec une heure largement dépassée signale immédiatement le point de blocage.

$ wp cron event list --fields=hook,next_run_relative,recurrence
+---------------------------+---------------------+------------+
| hook                      | next_run_relative    | recurrence |
+---------------------------+---------------------+------------+
| headless_sync_dispatch    | -2 hours             | 5 minutes  |
| wp_version_check          | 8 hours              | 12 hours   |
+---------------------------+---------------------+------------+

Un next_run_relative négatif pour headless_sync_dispatch confirme que la tâche est en retard, ce qui n’a rien d’anormal en soi tant qu’elle finit par se déclencher au chargement suivant. Le vrai problème apparaît quand ce retard persiste pendant des heures, signe que le pseudo-cron ne se déclenche plus du tout, souvent parce que le site tourne derrière un cache de page agressif qui sert des réponses sans jamais exécuter le PHP nécessaire au déclenchement du cron.

Correctif : rejouer l’évènement immédiatement

Plutôt que d’attendre un hypothétique passage naturel, wp cron event run permet de forcer l’exécution d’un hook précis, indépendamment de sa date prévue :

$ wp cron event run headless_sync_dispatch
Executed the cron event 'headless_sync_dispatch' in 0.412s.
Success: Executed a total of 1 cron event.

Cette commande exécute réellement la callback attachée au hook, avec les mêmes arguments que ceux enregistrés lors de la planification. Si la callback appelle wp_remote_post() vers un service de build, l’appel part immédiatement, et l’on peut vérifier son résultat dans la réponse retournée par WP-CLI en ajoutant --debug pour voir les éventuelles erreurs PHP masquées en production.

Dans certains cas, l’évènement n’apparaît même plus dans la liste : il a été supprimé sans être reprogrammé, souvent à cause d’une désactivation puis réactivation d’extension. Un wp cron event schedule headless_sync_dispatch now +5minutes permet de le réinjecter proprement dans la file avant de le rejouer.

Prévention : une supervision qui ne coûte rien

Le pseudo-cron de WordPress fonctionne bien tant qu’il reçoit un minimum de trafic HTTP régulier. Sur un site en coulisses d’un front headless, ce trafic peut être quasi nul, puisque les visiteurs consultent uniquement le front statique.

• Désactiver le pseudo-cron via la constante DISABLE_WP_CRON dans wp-config.php
• Déclencher wp cron event run --due-now par une tâche système planifiée, toutes les cinq minutes
• Ajouter un journal applicatif simple autour de la callback pour tracer chaque tentative de dispatch

Un cron applicatif qui ne journalise rien de ses échecs finira, un jour ou l’autre, par échouer en silence pendant plusieurs jours d’affilée.

Cette approche déplace la responsabilité de la planification vers un ordonnanceur système fiable, ce qui élimine la dépendance au trafic réel du site pour faire vivre la synchronisation.

En résumé

Un rebuild statique qui semble bloqué se diagnostique en trois commandes : lister la file avec wp cron event list, rejouer le hook en retard avec wp cron event run, puis sécuriser le déclenchement avec un cron système plutôt que le pseudo-cron par défaut. Cet article ne couvre volontairement pas les files d’attente tierces de type Redis ou RabbitMQ, qui posent des problèmes différents une fois la synchronisation confiée à un intermédiaire externe.