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. Para obter o tutorial que demonstra como usar webhooks com um GitHub App, confira Criar um Aplicativo GitHub que responde a eventos de webhook.
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 no GitHub App, você deverá ativar webhooks no registro do GitHub App e especificar uma URL de webhook em que o GitHub enviará os conteúdos do webhook.
Se o GitHub App não precisar responder aos webhooks ou só for usado para autenticação, você poderá desativar a função de webhook para o registro do GitHub App. Você não precisa especificar uma URL de webhook.
Para obter mais informações sobre como registrar o GitHub App, confira Registrar um Aplicativo GitHub. Para obter mais informações sobre como alterar os webhooks que o registro do GitHub App assina, confira Modificar um registro do Aplicativo GitHub.
Escolher uma URL de webhook
Ao ativar webhooks no registro 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" na página de registro do GitHub App. Para saber mais, confira Registrar um Aplicativo GitHub e Modificar um registro do 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 do webhook para seu Aplicativo GitHub, digite um token secreto em "Segredo do webhook" na página de registro do GitHub App. Você deve escolher uma cadeia de caracteres aleatória de texto com alta entropia. Para saber mais, confira Registrar um Aplicativo GitHub e Modificar um registro do 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 saber mais, confira Validação de entregas de webhooks.
Assinar eventos de webhook
Você pode assinar seu GitHub App para receber conteúdo de webhook para eventos específicos. Os eventos de webhook específicos que você pode selecionar no registro do GitHub App são determinados pelo tipo de permissões selecionado para seu aplicativo. Primeiro, você precisará selecionar as permissões que deseja que seu aplicativo tenha e depois assinar o aplicativo em eventos de webhook relacionados a esse conjunto de permissões. 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.