Webhooks de build & publication

Chinaski peut notifier des systèmes externes quand quelque chose se produit (la fin d'un build, la publication de contenu programmé, la modification d'un post) en envoyant un webhook signé vers une URL que vous configurez. Il n'accepte pas de webhooks pour déclencher des builds ; il les envoie seulement après que l'événement s'est produit.

Où les configurer

Sous Settings → Integrations :

Build Webhook URL : notifiée après un build statique réussi.
Publish Webhook URL : notifiée quand du contenu programmé est auto-publié.
Webhook Secret : secret partagé utilisé pour signer toutes les livraisons de webhooks.

Rien ne se déclenche en mode air-gap : tout envoi de webhook y est désactivé.

Le webhook de build

Quand un build réussit, Chinaski envoie un corps JSON en POST vers votre Build Webhook URL avec :

status : « ok »
built_at : quand le build s'est terminé (timestamp unix)
site_url : votre Site URL configurée
langs : la liste de vos codes de langue actifs

Utilisez-le pour lancer un pipeline de déploiement, pinguer votre CDN pour revalidation, ou rafraîchir n'importe quel cache externe.

Le webhook de publication

Quand du contenu programmé passe en ligne (le scheduler à la minute se déclenche), la Publish Webhook URL reçoit la notification avant l'e-mail de notification optionnel et le rebuild déclenché. C'est ainsi que les systèmes en aval peuvent commencer à mettre en cache ou à traduire le contenu dès qu'il devient public.

Vérifier que les livraisons viennent de Chinaski

Si vous avez défini un Webhook Secret, chaque POST inclut un en-tête :

X-Chinaski-Signature: sha256=<hex>

La valeur hex est le digest HMAC-SHA256 des octets exacts du corps, en utilisant votre secret partagé comme clé. Recalculez le digest sur le corps brut de votre côté et comparez avant de faire confiance au payload.

Les post webhooks (un système séparé) filtrent en plus par événement : la liste configurée doit être un sous-ensemble de published, updated, deleted ; un nom non reconnu est abandonné, une liste sans rien de valide retombe sur les trois valeurs par défaut, et une liste stockée sans entrée valide signifie que le hook ne se déclenche jamais.

Contraintes appliquées par l'expéditeur

Les cibles doivent être des URL publiques. Les webhooks visant la loopback, des plages de réseau privé, ou des destinations non résolubles sont refusés.
POST par défaut avec un corps Content-Type: application/json. Si la méthode d'une livraison est personnalisée, vous pouvez aussi utiliser PUT ou PATCH ; GET et les autres verbes ne sont pas utilisés.
Aucune redirection n'est suivie. Si votre endpoint redirige, Chinaski ne la suivra pas ; répondez directement à l'URL que vous configurez.
Des limites de taille de réponse s'appliquent : le webhook de build la lit en entier ; les autres hooks plafonnent le corps de réponse capturé à ~64 Kio. Les timeouts de connexion/requête/inactivité sont définis par type de webhook (défaut : 5 s de connexion, 10 s de requête, 30 s d'inactivité).
Seules les réponses de 200 à 299 comptent comme succès : tout le reste est enregistré et mis en file pour réessai.

Livraison at-least-once et réessais

Un webhook qui échoue (y compris timeouts de résolution et réponses non-2xx) est mis en file pour réessai : le premier à +1 minute, le deuxième à +10 minutes, le troisième à +1 heure. Un worker vérifie les réessais dus toutes les 30 secondes, en envoyant depuis le payload stocké. Les réessais réécrivent l'enregistrement de livraison plutôt que d'en créer de nouveaux, donc chaque livraison a une entrée de file.

Protection contre les cibles peu fiables

Si une cible échoue en continu, son circuit breaker se déclenche et la livraison vers elle est mise en pause : une cible sautée avec breaker ouvert ne génère pas davantage de lignes. Côté admin, sur l'écran Webhooks, le log de livraison montre la réponse pour chaque envoi, et il y a un bouton reset circuit-breaker pour restaurer manuellement un endpoint.

Le log de livraison garde une queue glissante d'historique par cible plutôt qu'une croissance illimitée, gardant votre db légère tout en vous permettant de confirmer ce qui s'est passé, quand, et le payload qui a voyagé.

Les post webhooks sont séparés

Un système distinct de post webhook vous permet d'enregistrer des endpoints par événement (published / updated / deleted) avec leurs propres secrets et filtres d'événements ; voir la page correspondante pour les événements, payloads, et détails de template.