O Que É um Webhook? Callbacks HTTP Orientados a Eventos
Um webhook é um callback HTTP definido pelo usuário: quando algo acontece, um serviço envia uma requisição HTTP para uma URL que você registrou, empurrando o evento até você em vez de fazê-lo consultar repetidamente.
Consultar uma API repetidamente perguntando "já tem algo novo" é um desperdício. Webhooks invertem isso: você dá uma URL a um serviço, e ele posta nessa URL no momento em que um evento ocorre. Pushes, merges e releases disparam o CI através de webhooks, tornando-os a espinha dorsal de pipelines orientados a eventos.
Push, não poll
Você registra um endpoint com um provedor. Quando o evento correspondente acontece, o provedor envia um HTTP POST com um payload descrevendo-o. Seu serviço reage imediatamente em vez de descobrir a mudança em seu próximo poll.
O que dispara webhooks de CI
- Um push para uma branch.
- Um pull request aberto ou atualizado.
- Uma tag ou release criada.
- Uma mudança de status de deployment.
Verificando autenticidade
Como qualquer um poderia fazer POST para sua URL, os provedores assinam os payloads com um segredo compartilhado. O receptor verifica a assinatura antes de confiar na requisição, o que impede que eventos falsificados disparem pipelines.
A entrega é best-effort
Webhooks podem ser perdidos se seu endpoint estiver brevemente fora do ar ou lento. Bons provedores fazem retry de entregas que falharam e expõem um log de tentativas para que você possa reproduzir eventos que não chegaram.
Webhooks em CI/CD
O evento que inicia um pipeline geralmente é um webhook do seu host de código-fonte. Deploys também enviam webhooks para fora, por exemplo para notificar um canal de chat ou atualizar uma página de status quando um release é concluído.
Falhas de entrega transitórias
Um receptor retornando um 5xx durante uma instabilidade momentânea faz o provedor tentar novamente mais tarde, então uma breve indisponibilidade raramente perde eventos. Os endpoints de runner da Latchkey toleram instabilidades transitórias e dependem dos retries do provedor para que uma única entrega falha não descarte silenciosamente um gatilho de build.
Principais conclusões
- Um webhook é um callback HTTP que empurra eventos em vez de ser consultado.
- Os payloads são assinados para que os receptores possam verificar se são genuínos.
- A entrega é best-effort com retries, então projete os receptores para serem idempotentes.