Webhooks de Build y Publish

Chinaski puede notificar a sistemas externos cuando ocurre algo (un build terminando, la publicación de contenido programado, un post que cambia) enviando un webhook firmado a una URL que configures. No acepta webhooks para disparar builds; solo los envía después de que el evento ocurrió.

Dónde se configuran

En Settings → Integrations:

• Build Webhook URL: se notifica tras un build estático exitoso.
• Publish Webhook URL: se notifica cuando el contenido programado se publica automáticamente.
• Webhook Secret: secreto compartido usado para firmar todas las entregas de webhooks.

Nada se dispara en modo air-gap: todo el envío de webhooks está deshabilitado ahí.

El webhook de build

Cuando un build tiene éxito, Chinaski hace POST de un cuerpo JSON a tu Build Webhook URL con:

• status: "ok"
• built_at: cuándo terminó el build (timestamp unix)
• site_url: tu Site URL configurada
• langs: la lista de tus códigos de idioma activos

Úsalo para disparar un pipeline de despliegue, hacer ping a tu CDN para revalidar, o refrescar cualquier caché externa.

El webhook de publish

Cuando el contenido programado sale a la luz (el scheduler de tick por minuto se dispara), la Publish Webhook URL recibe la notificación antes del correo de notificación opcional y del rebuild que se desencadena. Así es como los sistemas posteriores pueden empezar a cachear o traducir contenido en el momento en que se hace público.

Verificar que las entregas vienen de Chinaski

Si configuraste un Webhook Secret, cada POST incluye una cabecera:

X-Chinaski-Signature: sha256=<hex>

El valor hex es el digest HMAC-SHA256 de los bytes exactos del cuerpo, usando tu secreto compartido como clave. Recalcula el digest sobre el cuerpo crudo en tu lado y compara antes de confiar en el payload.

Los post webhooks (un sistema aparte) además filtran por evento: la lista configurada debe ser un subconjunto de published, updated, deleted; un nombre no reconocido se descarta, una lista sin nada válido recurre a los tres valores por defecto, y una lista guardada sin entradas válidas significa que el hook nunca se dispara.

Restricciones que aplica el remitente

• Los destinos deben ser URLs públicas. Los webhooks dirigidos a loopback, rangos de red privada o destinos no resolubles son rechazados.
• POST por defecto con un cuerpo Content-Type: application/json. Si el método de una entrega se personaliza, también puedes usar PUT o PATCH; GET y otros verbos no se usan.
• No se siguen redirecciones. Si tu endpoint redirige, Chinaski no lo seguirá; responde directamente en la URL que configures.
• Aplican límites de tamaño de respuesta: el webhook de build la lee completa; los demás hooks limitan el cuerpo de respuesta capturado a ~64 KiB. Los timeouts de conexión, petición e inactividad se definen por tipo de webhook (por defecto 5 s de conexión, 10 s de petición, 30 s de inactividad).
• Solo las respuestas 200 a 299 cuentan como éxito: cualquier otra se registra y se pone en cola para reintento.

Entrega at-least-once y reintentos

Un webhook que falla (incluyendo timeouts de resolución y respuestas no-2xx) se pone en cola para reintento: el primero a +1 minuto, el segundo a +10 minutos, el tercero a +1 hora. Un worker revisa los reintentos vencidos cada 30 segundos, enviando desde el payload almacenado. Los reintentos reescriben el registro de entrega en lugar de crear registros nuevos, así que cada entrega tiene una sola entrada en la cola.

Protección contra destinos inestables

Si un destino sigue fallando, su circuit breaker se activa y la entrega hacia él se pausa: un destino omitido con el breaker abierto no genera más filas. Del lado del admin, en la pantalla Webhooks, el log de entregas muestra la respuesta de cada envío, y hay un botón de reset circuit-breaker para restaurar manualmente un endpoint.

El log de entregas conserva una cola de historial rotativa por destino en lugar de crecer sin límite, manteniendo tu db ligera y aun así permitiéndote confirmar qué pasó, cuándo, y el payload que viajó.

Los post webhooks son un sistema aparte

Un sistema de post webhook distinto te permite registrar endpoints por evento (published / updated / deleted) con sus propios secretos y filtros de eventos; consulta la página correspondiente para eventos, payloads y detalles de plantillas.