Sobre webhooks e GitHub Apps
Os webhooks permitem que seu GitHub App receba notificações em tempo real quando eventos acontecem em GitHub, como quando alguém faz push de um commit ou abre um pull request em um repositório que seu app pode acessar. Para obter mais informações sobre webhooks, confira Sobre webhooks. Para ver um tutorial que mostra como usar webhooks com um GitHub App, consulte Criando um aplicativo GitHub que responde a eventos de webhook.
Você pode configurar seu GitHub App para receber webhooks de eventos específicos em GitHub e executar ações automaticamente com base neles. 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ê deve habilitar webhooks para seu GitHub App registro e especificar uma URL de webhook para onde GitHub enviará os conteúdos do webhook.
Se o seu GitHub App não precisar responder a webhooks ou for usado apenas para autenticação, você poderá desativar a funcionalidade de webhook no registro do seu GitHub App. Você não precisa especificar uma URL de webhook.
Para obter mais informações sobre como registrar um GitHub App, consulte Registrando um aplicativo GitHub. Para obter mais informações sobre como alterar os webhooks a que um GitHub App registro está inscrito, consulte Modificando um registro de aplicativo GitHub.
Escolher uma URL de webhook
Ao ativar webhooks para seu GitHub App registro, você precisará especificar uma URL de webhook. A URL do webhook é o endereço de um servidor Web que receberá os conteúdos de eventos do webhook enviados para seu GitHub App. O servidor pode então executar uma ação com base no conteúdo da carga útil. Você deve escolher um servidor web apropriado para o volume de tráfego de webhooks que o seu GitHub App enfrentará.
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, onde GitHub pode enviar cargas de 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 do Webhook do Smee como a URL do webhook para sua 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 à sua GitHub App, insira seu domínio exclusivo do Smee no campo "URL do Webhook" na sua página de registro GitHub App. Para saber mais, confira Registrando um aplicativo GitHub e Modificando um registro de 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 lado 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 GitHub API.
Para lidar com um volume maior de tráfego de webhooks para um aplicativo de grande porte em produção, considere usar o processamento assíncrono de webhooks em um servidor dedicado. Você pode fazer isso empregando uma fila, onde o manipulador de webhook empurra dados para a fila, e processos separados realizam ações subsequentes 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 apenas às que se originam de GitHub. Você pode fazer isso criando um segredo de webhook para seu aplicativo.
Para criar um segredo de webhook para seu aplicativo GitHub, digite um token secreto em "Segredo do Webhook" na página GitHub App de registro. Você deve escolher uma cadeia de caracteres aleatória de texto com alta entropia. Para saber mais, confira Registrando um aplicativo GitHub e Modificando um registro de 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 inscrever seu GitHub App para receber payloads de webhook de 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, consulte 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.