Sobre webhooks
Os Webhooks permitem que você assine eventos que acontecem em um sistema de software e receba automaticamente uma entrega de dados ao seu servidor sempre que esses eventos ocorrerem.
Webhooks são usados para receber dados conforme eles acontecem, em vez de pesquisar uma API (chamar uma API intermitentemente) para ver se há dados disponíveis. Com webhooks, você só precisa expressar interesse em um evento uma vez, ao criar o webhook.
Webhooks são usados em uma ampla variedade de cenários, incluindo:
- Acionar pipelines de CI (integração contínua) em um servidor de CI externo. Por exemplo, para acionar a CI no Jenkins ou no CircleCI quando o código é enviado a uma ramificação.
- Envio de notificações sobre eventos no GitHub para plataformas de colaboração. Por exemplo, enviar uma notificação ao Discord ou Slack quando houver uma revisão em uma solicitação de pull.
- Atualização de um rastreador de problemas externo, como o Jira.
- Implementação em um servidor de produção.
- Registro de eventos à medida que eles ocorrem no GitHub para fins de auditoria.
Sobre webhooks no GitHub
Ao criar um webhook, você especifica uma URL e assina eventos que ocorrem no GitHub. Quando ocorrer um evento no qual seu webhook está inscrito, o GitHub enviará uma solicitação HTTP com dados sobre o evento para o URL que você especificou. Se o seu servidor estiver configurado para ouvir entregas de webhooks nesse URL, ele poderá agir quando receber um.
Por exemplo, você pode inscrever seu webhook em eventos que ocorrem quando o código é enviado por push para um repositório, uma solicitação pull é aberta, um site do GitHub Pages é criado ou um novo membro é adicionado a uma equipe. O servidor pode responder implantando código na produção, acionando um pipeline de CI, enviando uma notificação ou criando um projeto do GitHub para o novo membro da equipe.
Você deve criar um webhook em um repositório, organização, GitHub Enterprise, ou GitHub App. O webhook só pode acessar recursos que estão disponíveis no repositório, organização, conta GitHub Enterprise, ou GitHub App em que está instalado. Para obter mais informações, confira "Tipos de webhooks".
Para obter mais informações sobre a criação de webhooks, consulte "Criar webhooks". Para obter mais informações sobre os tipos de eventos que você pode assinar, consulte "Eventos e cargas de webhook". Para obter mais informações sobre como configurar o servidor para executar uma ação em resposta a uma entrega de conteúdo, consulte "Lidar com entregas de webhook".
Observação: os webhooks do GitHub atualmente não dão suporte ao IPv6, mas irão no futuro. O ponto de extremidade da API REST /meta retorna intervalos IPv6 para habilitar essa transição.
Escolher webhooks ou a API REST
O uso de webhooks tem as seguintes vantagens em relação ao uso da API:
- Webhooks exigem menos esforço e menos recursos do que a sondagem de uma API.
- Webhooks são mais escalonáveis do que chamadas de API. Se você precisar monitorar muitos recursos, chamar a API para cada recurso pode fazer com que você atinja rapidamente a cota de limite de taxa da API. Em vez disso, você pode assinar vários eventos de webhook e receber informações somente quando um evento ocorrer.
- Webhooks permitem atualizações quase em tempo real, pois são acionados quando ocorre um evento.
Se você precisar de informações apenas uma vez ou de forma intermitente ou se quiser obter informações apenas de um pequeno conjunto de recursos sem planos de expansão, poderá chamar a API quando precisar das informações relevantes.
Para obter informações sobre as práticas recomendadas a serem seguidas ao usar webhooks, consulte "Melhores práticas para usar webhooks".
Nota: o GitHub Services (às vezes chamado de Service Hooks) foi sunset a favor da integração com webhooks. Para obter mais informações sobre como migrar sua integração do uso dos Serviços do GitHub para o uso de webhooks, consulte a postagem do blog.