Webhooks

Chinaski puede notificar a tus otros sistemas sobre lo que sucede en el CMS enviando webhooks salientes. Existen cuatro clases; form submissions, eventos de post, publicaciones de contenido programado y builds completados; cada uno configurado donde sucede: ajustes por form, la lista de post-webhooks, o los ajustes de build/publish en el área de admin. Esta página cubre qué se envía, cómo está protegido, y qué pasa cuando una entrega falla.

Cómo funciona una entrega

Los webhooks salientes son peticiones HTTP JSON. El endpoint receptor obtiene:

Un body JSON (el event payload, o tu template de body personalizado con las variables llenadas).
Content-Type: application/json.
Si estableces un secret de firma: un header X-Chinaski-Signature: sha256=… que contiene un HMAC-SHA256 del body exacto de la petición, así los receptores pueden verificar que la petición realmente vino de Chinaski.
El método HTTP es POST por defecto; PUT y PATCH también funcionan; cualquier otra cosa se envía como POST.
Headers personalizados opcionales, uno por línea en forma Name: value, según configuración.

De dónde vienen los eventos

Form webhooks; enviados después de cada form submission, configurados por form (URL, secret de firma, método, headers personalizados, template de body personalizado).
Post webhooks; puedes registrar destinos con nombre bajo los ajustes de post-webhook, cada uno suscrito a un subconjunto de eventos published, updated, deleted. Se envían por cualquier cambio de post coincidente. El payload incluye el nombre del evento, ID del post, slug, título, idioma, URL absoluta del post, flag de publicado, author, categoría, tags y timestamp.
Publish webhooks; cuando el contenido programado alcanza su hora de publish, un único payload por lotes content_published se envía a la URL de publish que configuraste, listando los ítems; se firma con tu webhook secret global.
Build webhooks; después de un build exitoso, {status: 'ok', built_at: …, site_url: …, langs: […]} a la URL del build webhook.

Las URLs viejas de entrega de posts de setups previos que nunca se reconfiguraron siguen funcionando: una URL legacy de todos-los-eventos sigue recibiendo los tres eventos de posts sin firmar.

Primero la seguridad

Los destinos de webhook deben ser direcciones http/https públicas. Las direcciones privadas/internas (localhost, loopback, rangos de IP privados, codificaciones de hostname Unicode y similares) se rechazan de plano; esto evita que un editor apunte webhooks a servicios internos.
No se siguen redirects.
Los timeouts son cortos (típicamente 5 s para conectar, 10 s en total), y las respuestas de más de 64 KiB se cortan en el path de lectura (los publish y build webhooks leen tamaño ilimitado con timeouts más largos). Los fallos de entrega no bloquean la edición de contenido.
Un destino que falla entra en cooldown de circuit breaker: después de 5 fallos consecutivos contra la misma URL, esa URL se salta por una hora completa (cualquier éxito resetea el conteo). Esto protege a Chinaski y a tu red de un endpoint muerto.

Fallos y reintentos

Una respuesta no-2xx (o un fallo de conexión) no es el final:

Las entregas fallidas se reintentan automáticamente hasta tres veces, tras 1 minuto, 10 minutos, luego 1 hora.
Los reintentos corren en un worker de segundo plano que toma entregas pendientes cada 30 segundos; el claim es atómico, así que dos pases de entrega nunca doble-envían el mismo intento.
También puedes reintentar cualquier entrega manualmente desde las vistas de webhook en el área de admin.

Cada intento; éxito o fallo; se registra en un delivery log: el tipo de webhook, la URL objetivo, el payload enviado, el estado de respuesta y body (los body de respuesta se truncan a 10,000 caracteres) y un mensaje de error. Los registros de entrega exitosa se podan después de 30 días; los fallidos se conservan para que puedas diagnosticarlos y reintentarlos manualmente.

Cosas exigentes que saber en la práctica

Los webhooks salientes están limitados a 8 concurrentes; los lotes más pesados encolan sus envíos en orden en lugar de soltarlos.
El modo air-gap (CHINASKI_AIRGAP=1) deshabilita las cuatro clases de webhook además del worker de reintento automático y los reintentos manuales; no configures nada si nunca esperas tráfico saliente, dado que las entregas tampoco pueden suceder sin que el modo air-gap esté deshabilitado.
Los secrets de firma de webhook se almacenan cifrados en la base de datos; deja el campo vacío al guardar para conservar el secret existente.