Sobre webhooks

Sobre webhooks

Webhooks são um método de comunicação que permite aos usuários assinar eventos que ocorrem em um sistema de software. Os webhooks podem ser disparados sempre que eventos específicos ocorrem em GitHub. Por exemplo, você pode configurar um webhook para ser disparado sempre que:

• O código é enviado por push para um repositório
• Uma pull request é aberta
• Um site do GitHub Pages é construído
• Um novo integrante é adicionado a uma equipe

Você pode criar webhooks para um GitHub Enterprise, uma organização, um repositório ou um GitHub App. Você também pode criar webhooks para assinar eventos relacionados a GitHub Sponsors e GitHub Marketplace.

Você pode criar até 250 webhooks para cada evento em cada destino de instalação (organização específica ou repositório específico).

Para obter mais informações sobre a criação de webhooks, consulte "Criar webhooks".

Sobre eventos de webhooks

Ao configurar um webhook, você pode escolher quais eventos enviarão cargas úteis. Para limitar o número de solicitações HTTP feitas ao servidor, você deve inscrever apenas os eventos específicos que planeja manipular. Para obter uma lista completa de eventos de webhooks e seus conteúdos, consulte "Eventos e cargas de webhook".

Alguns eventos de webhooks têm ações, que são operações que podem ser executadas no recurso que o evento de webhook representa. Se um evento de webhook tiver vários tipos de ação, cada ação acionará uma entrega de conteúdo. Por exemplo, o evento de webhook package acionará uma entrega de conteúdo quando um pacote for updated ou edited. Não é possível assinar ações de webhooks individuais. Ao configurar um webhook, você receberá conteúdos para todas as ações relacionadas a ele.

Por padrão, os webhooks instalados em uma organização ou um repositório apenas são assinados para o evento push. Por padrão, os webhooks em GitHub Apps não estão inscritos em nenhum evento. Você pode alterar os eventos nos quais um webhook está inscrito a qualquer momento.

Sobre as entregas de webhook

Quando você receber uma entrega de webhook, o conteúdo incluirá o nome do evento e a ação que acionou a entrega, juntamente com outras informações sobre o evento propriamente dito. Para obter mais informações sobre os cabeçalhos de entrega que são incluídos em cada conteúdo e um exemplo de entrega, consulte "Eventos e cargas de webhook". Algumas informações são incluídas na maioria ou em todas as entregas de webhooks, como o usuário que realizou o evento, a organização ou o repositório em que o evento ocorreu.

Ao criar um webhook, você precisará especificar um URL no qual deseja receber os eventos desse webhook. GitHub enviará uma carga HTTP POST para essa URL quando ocorrerem eventos em que o webhook está inscrito. Seu servidor poderá então processar e responder ao webhook. Para obter mais informações, confira "Lidar com entregas de webhook".

Para obter informações sobre a visualização de entregas de webhooks, consulte"Visualizar entregas do webhook".

Quando usar webhooks

Webhooks podem ser 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.

Webhooks permitem que você receba dados à medida que eles acontecem, em vez de chamar uma API intermitentemente para ver se os dados estão disponíveis, processo também conhecido como sondagem de atualizações. Você precisa apenas manifestar interesse em um evento uma vez, ao criar o webhook.

Webhooks têm 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".

Sobre as permissões para gerenciar webhooks

Para gerenciar webhooks, você deve ser proprietário ou ter acesso de administrador ao recurso no qual o webhook foi criado e no qual está ouvindo eventos. Por exemplo, para gerenciar webhooks da organização, você precisa de permissões de administrador para essa organização. Para obter mais informações sobre a criação de diferentes tipos de webhook, consulte "Criar webhooks".

Substituir o GitHub Services herdado por webhooks

O GitHub Services (às vezes chamado de Service Hooks) é o método legado de integração em que o GitHub hospedava uma parte dos serviços do nosso integrador por meio do repositório github-services. Em 2019, descontinuamos o GitHub Services em favor da integração com webhooks. Para obter mais informações sobre a descontinuidade, consulte esta publicação de blog.