Webhooks

Chinaski peut notifier vos autres systèmes de ce qui se passe dans le CMS en envoyant des webhooks sortants. Quatre types existent : submissions de formulaires, événements de posts, publications de contenu planifié et builds terminés ; chacun configuré là où il se produit : réglages par formulaire, liste des post-webhooks, ou réglages build/publish dans la zone admin. Cette page couvre ce qui est envoyé, comment c'est protégé, et ce qui se passe quand une livraison échoue.

Comment se déroule une livraison

Les webhooks sortants sont des requêtes HTTP JSON. L'endpoint récepteur reçoit :

• Un body JSON (le payload de l'événement, ou votre template de body personnalisé avec les variables remplies).
• Content-Type: application/json.
• Si vous définissez un secret de signature : un en-tête X-Chinaski-Signature: sha256=… contenant un HMAC-SHA256 du body exact de la requête, pour que les récepteurs puissent vérifier que la requête vient vraiment de Chinaski.
• La méthode HTTP est POST par défaut ; PUT et PATCH fonctionnent aussi ; tout le reste est envoyé en POST.
• Des en-têtes personnalisés optionnels, un par ligne sous la forme Name: value, comme configurés.

D'où viennent les événements

• Webhooks de formulaire: envoyés après chaque submission de formulaire, configurés par formulaire (URL, secret de signature, méthode, en-têtes personnalisés, template de body personnalisé).
• Webhooks de post: vous pouvez enregistrer des cibles nommées sous les réglages des post-webhooks, chacune s'abonnant à un sous-ensemble des événements published, updated, deleted. Envoyés pour tout changement de post correspondant. Le payload inclut le nom de l'événement, l'ID du post, le slug, le titre, la langue, l'URL absolue du post, le flag de publication, l'auteur, la catégorie, les tags et le timestamp.
• Webhooks de publication: quand le contenu planifié atteint son heure de publication, un unique payload batch content_published est envoyé à l'URL de publication que vous avez configurée, listant les éléments ; il est signé avec votre secret de webhook global.
• Webhooks de build: après un build réussi, {status: 'ok', built_at: …, site_url: …, langs: […]} vers l'URL du webhook de build.

Les anciennes URL de livraison de posts de configurations précédentes jamais reconfigurées continuent de fonctionner : une URL legacy tous-événements continue de recevoir les trois événements de post non signés.

La sécurité d'abord

• Les cibles de webhook doivent être des adresses http/https publiques. Les adresses privées/internes (localhost, loopback, plages d'IP privées, encodages de hostname Unicode, et similaires) sont rejetées catégoriquement : cela empêche un éditeur de pointer des webhooks vers des services internes.
• Aucune redirection n'est suivie.
• Les timeouts sont courts (typiquement 5 s pour se connecter, 10 s au total), et les réponses de plus de 64 Kio sont coupées sur le chemin de lecture (les webhooks publish et build lisent une taille illimitée avec des timeouts plus longs). Les échecs de livraison ne bloquent pas l'édition de contenu.
• Une cible en échec est mise en refroidissement de circuit-breaker : après 5 échecs consécutifs vers la même URL, cette URL est sautée pendant une heure entière (tout succès réinitialise le compte). Cela protège Chinaski et votre réseau d'un endpoint mort.

Échecs et retries

Une réponse non 2xx (ou un échec de connexion) n'est pas la fin :

• Les livraisons en échec sont retentées automatiquement jusqu'à trois fois, après 1 minute, 10 minutes, puis 1 heure.
• Les retries tournent dans un worker d'arrière-plan qui récupère les livraisons en attente toutes les 30 secondes ; une revendication est atomique, donc deux passes de livraison n'envoient jamais en double la même tentative.
• Vous pouvez aussi retenter n'importe quelle livraison manuellement depuis les vues webhook dans la zone admin.

Chaque tentative, succès ou échec, est enregistrée dans un journal de livraison : le type de webhook, l'URL cible, le payload envoyé, le statut et le body de la réponse (les body de réponse sont tronqués à 10 000 caractères), et un message d'erreur. Les enregistrements de livraison réussis sont élagués après 30 jours ; ceux en échec sont conservés pour que vous puissiez les diagnostiquer et les retenter manuellement.

Choses exigeantes à savoir en pratique

• Les webhooks sortants sont plafonnés à 8 requêtes simultanées ; les lots plus lourds mettent leurs envois en file d'attente dans l'ordre plutôt que de les abandonner.
• Le mode air-gap (CHINASKI_AIRGAP=1) désactive les quatre types de webhook ainsi que le worker de retry automatique et les retries manuels ; ne configurez rien si vous n'attendez jamais de trafic sortant, puisque les livraisons ne peuvent de toute façon pas se produire sans que le mode air-gap soit désactivé.
• Les secrets de signature de webhook sont stockés chiffrés dans la base de données ; laissez le champ vide à la sauvegarde pour garder le secret existant.