Webhooks de Build e Publicação

O Chinaski pode notificar sistemas externos quando algo acontece: um build terminando, publicação agendada de conteúdo, um post mudando: enviando um webhook assinado a uma URL que você configura. Ele não aceita webhooks para disparar builds; apenas envia depois que o evento aconteceu.

Onde você os configura

Em Settings → Integrações:

• URL do Build Webhook: notificada após um build estático bem-sucedido.
• URL do Publish Webhook: notificada quando conteúdo agendado é autopublicado.
• Segredo dos Webhooks: segredo compartilhado usado para assinar todas as entregas de webhook.

Nada dispara no modo air-gap: todo o envio de webhooks está desabilitado ali.

O build webhook

Quando um build tem sucesso, o Chinaski envia um POST com corpo JSON para sua URL de Build Webhook com:

• status: “ok”
• built_at: quando o build terminou (timestamp unix)
• site_url: a URL de Site que você configurou
• langs: a lista dos seus códigos de idioma ativos

Use isto para disparar um pipeline de deployment, fazer ping no seu CDN para revalidar, ou atualizar qualquer cache externo.

O publish webhook

Quando conteúdo agendado vai ao ar (o scheduler de tique por minuto dispara), a URL do Publish Webhook recebe a notificação antes do e-mail de notificação opcional e do rebuild disparado. É assim que sistemas a jusante podem começar a cachear ou traduzir conteúdo no momento em que ele se torna público.

Verificando que as entregas vieram do Chinaski

Se você definiu um segredo de webhooks, cada POST inclui um header:

X-Chinaski-Signature: sha256=<hex>

O valor hex é o digest HMAC-SHA256 dos bytes exatos do corpo, usando seu segredo compartilhado como chave. Recalcule o digest sobre o corpo bruto do seu lado e compare antes de confiar no payload.

Post webhooks (um sistema separado) filtram adicionalmente por evento: a lista configurada deve ser um subconjunto de published, updated, deleted: um nome não reconhecido é descartado, uma lista sem nada de válido cai para os três padrões, e uma lista armazenada sem entradas válidas significa que o hook nunca dispara.

Restrições que o remetente aplica

• Os alvos devem ser URLs públicas. Webhooks apontados para loopback, faixas de rede privada ou destinos não resolvíveis são recusados.
• POST por padrão com corpo Content-Type: application/json. Se o método de uma entrega é personalizado, você pode usar PUT ou PATCH também: GET e outros verbos não são usados.
• Nenhum redirecionamento é seguido. Se o seu endpoint redireciona, o Chinaski não o seguirá: responda diretamente na URL que você configura.
• Limites de tamanho de resposta se aplicam: o build webhook lê tudo; os outros hooks limitam o corpo de resposta capturado a ~64 KiB. Timeouts de conexão/requisição/inatividade são definidos por tipo de webhook (padrão 5 s de conexão, 10 s de requisição, 30 s de inatividade).
• Apenas respostas 200: 299 contam como sucesso: qualquer outra coisa é registrada e colocada na fila para retry.

Entrega at-least-once e retries

Um webhook que falha (incluindo timeouts de resolução e respostas não-2xx) entra na fila de retry: o primeiro a +1 minuto, o segundo a +10 minutos, o terceiro a +1 hora. Um worker verifica retries vencidos a cada 30 segundos, enviando a partir do payload armazenado. Os retries reescrevem o registro de entrega em vez de criar novos, de modo que cada entrega tem uma entrada de fila.

Proteção contra alvos instáveis

Se um alvo continua falhando, seu circuit breaker dispara e a entrega a ele entra em pausa: um alvo com o breaker aberto e pulado não gera mais linhas. Do lado de admin, na tela Webhooks, o log de entregas mostra a resposta de cada envio, e há um botão reset circuit-breaker para restaurar manualmente um endpoint.

O log de entregas mantém uma cauda móvel de histórico por alvo em vez de crescimento ilimitado, mantendo seu db enxuto enquanto ainda permite confirmar o que aconteceu, quando, e o payload que viajou.

Post webhooks são separados

Um sistema distinto de post webhook permite registrar endpoints por evento (published / updated / deleted) com seus próprios segredos e filtros de evento: veja a página correspondente para eventos, payloads e detalhes de template.