Sobre os webhooks e o GitHub Apps
Os webhooks permitem que seu GitHub App receba notificações em tempo real quando eventos acontecem no GitHub, como quando alguém envia um commit por push ou abre uma solicitação de pull em um repositório que seu aplicativo pode acessar. Para obter mais informações sobre webhooks, confira "Sobre webhooks".
Você pode configurar seu GitHub App para receber webhooks para eventos específicos no GitHub e tomar medidas automaticamente sobre eles. Para obter mais informações sobre os tipos de webhooks que você pode receber, confira "Eventos e cargas de webhook".
Para receber eventos de webhook em seu GitHub App, você deverá ativar webhooks nas configurações do aplicativo e especificar uma URL de webhook em que o GitHub enviará os conteúdos do webhook. Para obter mais informações sobre como criar ou configurar um GitHub App, confira "Criar um aplicativo GitHub".
Se o aplicativo não precisar responder a webhooks ou só for usado para autenticação, você poderá desativar a função de webhook nas configurações do aplicativo. Você não precisa especificar uma URL de webhook. Para obter mais informações, confira "Criar um aplicativo GitHub".
Para obter informações sobre como alterar os webhooks que um GitHub App assina, confira "Modificar um aplicativo GitHub".
Escolher uma URL de webhook
Ao ativar webhooks nas configurações do seu GitHub App, você precisará especificar uma URL de webhook. A URL do webhook é o endereço de um servidor Web que receberá o conteúdo do evento de webhook enviado para o GitHub App. O servidor pode executar uma ação com base no conteúdo. Você deve escolher um servidor Web apropriado para o volume de tráfego do webhook que seu GitHub App encontrará.
Escolher uma URL de webhook para desenvolvimento e teste
Ao desenvolver e testar seu aplicativo, você poderá usar um serviço de entrega de carga de webhook, como o Smee, para capturar e encaminhar conteúdo do webhook para seu ambiente de desenvolvimento local. Nunca use o Smee para um aplicativo em produção, pois os canais do Smee não são autenticados nem seguros. Como alternativa, você pode usar uma ferramenta como ngrok, localtunnel ou o Console do Hookdeck que expõe o computador local à Internet para receber o conteúdo.
Criar uma URL de webhook com o Smee
Você pode usar o Smee para criar um domínio exclusivo em que GitHub pode enviar conteúdo do webhook sem expor seu desenvolvimento local à Internet. O Smee chama esse domínio exclusivo de "URL de Proxy do Webhook". Você pode usar a URL do Proxy de Webhook do Smee como a URL do webhook para o seu GitHub App.
- Para usar o Smee para criar um domínio exclusivo, acesse https://smee.io e clique em Iniciar um novo canal.
- Na página do canal do Smee, siga as instruções em "Usar a CLI" para instalar e executar o cliente Smee.
- Para conectar a URL do webhook do Smee ao seu GitHub App, insira seu domínio Smee exclusivo no campo "URL do Webhook" das configurações do aplicativo. Para obter mais informações, confira "Criar um aplicativo GitHub".
Escolher uma URL do webhook para produção
Para um aplicativo em produção que recebe um baixo volume de tráfego de webhook, você poderá hospedá-lo em qualquer servidor de aplicativos dinâmico. O código do servidor para lidar com o webhook pode receber o evento, desserializar seu conteúdo JSON e decidir qual ação tomar, como armazenar os dados em um banco de dados ou chamar a API do GitHub.
Para lidar com um maior volume de tráfego de webhook para um aplicativo grande em produção, considere usar o tratamento de webhook assíncrono em um servidor dedicado. Você pode fazer isso aplicando uma fila, em que o manipulador de webhook envia dados por push para a fila, e separar ações subsequentes que executam processos com base nos eventos. Além disso, você pode usar funções de nuvem como Azure Functions, AWS Lambda ou Hookdeck para ajudar a dimensionar o aplicativo para lidar com grandes volumes de eventos de webhook.
Proteger seus webhooks com um segredo de webhook
Depois que o servidor é configurado para receber conteúdos, ele escuta os conteúdos enviados a ele. Por motivos de segurança, você deve limitar as solicitações de entrada somente às originadas do GitHub. Você pode fazer isso criando um segredo de webhook para seu aplicativo.
Para criar um segredo de webhook para o aplicativo GitHub, digite um token secreto nas configurações do aplicativo em "Segredo do webhook". Você deve escolher uma cadeia de caracteres aleatória de texto com alta entropia. Para obter mais informações sobre como criar um segredo de webhook nas configurações do aplicativo, confira "Criar um aplicativo GitHub".
Depois de criar um segredo de webhook para seu aplicativo, você precisará configurar o servidor para armazenar e validar com segurança o token secreto do webhook. Para obter mais informações, confira "Protegendo seus webhooks".
Assinar eventos de webhook
Você pode assinar seu GitHub App para receber conteúdo de webhook para eventos específicos. The specific webhook events that you can select in your app settings are determined by the type of permissions you selected for your app. You will first need to select the permissions you would like your app to have, and then you can subscribe your app to webhook events that are related to that set of permissions. Para obter mais informações, confira "Escolhendo permissões para um Aplicativo GitHub."
Por exemplo, se você quiser que seu aplicativo receba um conteúdo de evento de webhook sempre que um novo problema for aberto em seu repositório, primeiro você precisará conceder ao aplicativo permissão para acessar "Problemas" em "Permissões do repositório". Em "Assinar eventos", você pode selecionar "Problemas".
Para obter mais informações sobre as permissões necessárias para cada evento de webhook, confira "Eventos e cargas de webhook".