Webhooks

O Chinaski pode notificar seus outros sistemas sobre o que acontece no CMS enviando webhooks de saída. Quatro tipos existem (submissões de formulário, eventos de post, publicações de conteúdo agendado e builds concluídos), cada um configurado onde acontece: nas configurações por formulário, na lista de post-webhooks, ou nas configurações de build/publish na área de admin. Esta página cobre o que é enviado, como é protegido e o que acontece quando uma entrega falha.

Como uma entrega funciona

Os webhooks de saída são requisições HTTP em JSON. O endpoint receptor recebe:

Um corpo JSON (o payload do evento, ou seu template de corpo personalizado com as variáveis preenchidas).
Content-Type: application/json.
Se você definiu um segredo de assinatura: um header X-Chinaski-Signature: sha256=… contendo um HMAC-SHA256 do corpo exato da requisição, para que os receptores possam verificar que a requisição realmente veio do Chinaski.
O método HTTP é POST por padrão; PUT e PATCH também funcionam; qualquer outra coisa é enviada como POST.
Headers personalizados opcionais, um por linha na forma Name: value, conforme configurado.

De onde vêm os eventos

Webhooks de formulário: enviados após cada submissão de formulário, configurados por formulário (URL, segredo de assinatura, método, headers personalizados, template de corpo personalizado).
Webhooks de post: você pode registrar alvos nomeados nas configurações de post-webhook, cada um se inscrevendo em um subconjunto dos eventos published, updated, deleted. Enviados para qualquer mudança de post correspondente. O payload inclui o nome do evento, ID do post, slug, título, idioma, URL absoluta do post, flag de publicado, autor, categoria, tags e timestamp.
Webhooks de publish: quando o conteúdo agendado chega à sua hora de publicar, um único payload em lote content_published é enviado à URL de publish que você configurou, listando os itens; é assinado com seu segredo de webhook global.
Webhooks de build: após um build bem-sucedido, {status: 'ok', built_at: …, site_url: …, langs: […]} à URL do webhook de build.

URLs de entrega de post antigas, de configurações anteriores que nunca foram reconfiguradas, continuam a funcionar: uma URL legada de todos os eventos continua recebendo os três eventos de post sem assinatura.

Segurança primeiro

Os alvos de webhook devem ser endereços públicos http/https. Endereços privados/internos (localhost, loopback, faixas de IP privadas, codificações de hostname em Unicode e similares) são rejeitados de imediato: isso impede que um editor aponte webhooks a serviços internos.
Nenhum redirecionamento é seguido.
Os timeouts são curtos (tipicamente 5 s para conectar, 10 s no total), e respostas maiores que 64 KiB são cortadas no caminho de leitura (os webhooks de publish e build leem tamanho ilimitado com timeouts mais longos). Falhas de entrega não bloqueiam a edição de conteúdo.
Um alvo que falha entra em cooldown de circuit-breaker: após 5 falhas consecutivas à mesma URL, essa URL é pulada por uma hora completa (qualquer sucesso zera a contagem). Isso protege o Chinaski e sua rede de um endpoint morto.

Falhas e retries

Uma resposta não-2xx (ou falha de conexão) não é o fim:

Entregas com falha têm retry automaticamente até três vezes: após 1 minuto, 10 minutos, depois 1 hora.
Os retries executam em um worker em segundo plano que escolhe entregas pendentes a cada 30 segundos; a reivindicação é atômica, para que duas passagens de entrega nunca enviem duas vezes a mesma tentativa.
Você também pode tentar qualquer entrega de novo manualmente a partir das visões de webhook na área de admin.

Cada tentativa (sucesso ou falha) é registrada em um log de entregas: o tipo de webhook, a URL alvo, o payload que foi enviado, o status e corpo da resposta (os corpos de resposta são truncados em 10.000 caracteres) e uma mensagem de erro. Registros de entrega bem-sucedida são podados após 30 dias; os falhos são mantidos para que você possa diagnosticá-los e tentá-los manualmente de novo.

Coisas a saber na prática

Webhooks de saída são limitados a 8 requisições simultâneas; lotes mais pesados enfileiram seus envios em ordem em vez de descartá-los.
O modo air-gap (CHINASKI_AIRGAP=1) desabilita os quatro tipos de webhook, além do worker de retry automático e dos retries manuais; não configure nada se você nunca espera tráfego de saída, já que as entregas também não podem acontecer sem o modo air-gap estar desabilitado.
Os segredos de assinatura de webhook são armazenados criptografados no banco de dados; deixe o campo em branco ao salvar para manter o segredo existente.