Agora que entendemos os conceitos básicos de webhooks, vamos analisar o processo de criação da nossa própria integração com o webhook. Neste tutorial, vamos criar um webhook de repositório que será responsável por listar quão popular é o nosso repositório, com base no número de problemas que recebe por dia.
Criar um webhook é um processo de duas etapas. Primeiro, você deverá configurar como deseja que seu webhook se comporte através do GitHub Enterprise Server - quais eventos devem ser ouvidos. Em seguida, você irá configurar seu servidor para receber e gerenciar a carga.
You can use the repository, organization, and app webhook REST APIs to create, update, delete, and ping webhooks. For more information, see:
Configurar um Webhook
É possível instalar webhooks em uma organização ou em um repositório específico.
Para configurar um webhook, vá para a página de configurações do seu repositório ou organização. Nessa página, clique em Webhooks e, em seguida, Adicionar webhook.
Como alternativa, você pode optar por criar e gerenciar um webhook através da API de Webhooks.
Os webhooks exigem algumas opções de configuração antes de você poder usá-los. Iremos analisar cada uma destas configurações abaixo.
URL de carga
A URL doa carga é a URL do servidor que receberá as solicitações de POST do webhook.
Já que estamos desenvolvendo localmente para nosso tutorial, vamos definir como http://localhost:4567/payload. Vamos explicar o porquê na documentação Configurando seu servidor.
Tipo de conteúdo
Os webhooks podem ser entregues usando diferentes tipos de conteúdo:
- O tipo de conteúdo de
application/jsonfornecerá a carga do JSON diretamente como o texto da solicitaçãoPOST. - O tipo de conteúdo
application/x-www-form-urlencodedenviará a carga do JSON como um parâmetro de formulário denominadocarga.
Escolha o que melhor se adeque às suas necessidades. Para este tutorial, o tipo de conteúdo-padrão para application/json está certo.
Segredo
Definir um segredo de webhook permite que você certifique-se de que as solicitações POST enviadas para a URL da carga são de GitHub Enterprise Server. When you set a secret, you'll receive the X-Hub-Signature header in the webhook POST request. Para obter mais informações sobre como usar um segredo com um cabeçalho de assinatura para proteger as suas cargas do webhook, veja "Proteger seus webhooks."
Verificação de SSL
Se sua "URL da carga" for uma site seguro (HTTPS), você terá a opção de definir as configurações de verificação SSL. Se a sua "URL de carga " não for segura (HTTP), o GitHub não exibirá esta opção. Por padrão, o GitHub verifica o certificado SSL do seu site ao entregar as cargas de webhook. A verificação SSL ajuda a garantir que as cargas de hook sejam entregues no seu ponto de extremidade da URL de forma segura. Você tem a opção de desabilitar SSL, mas recomendamos manter a opção Habilitar a verificação de SSL selecionada.
Ativo
Por padrão, as entregas de webhook estão "Ativas". Você pode optar por desativar a entrega das cargas de webhook, desmarcando "Ativo".
Eventos
Os eventos encontram-se no núcleo dos webhooks. Esses webhooks são acionados sempre que uma determinada ação é tomada no repositório, a qual a URL da carga do seu servidor intercepta e e sobre a qual atua.
Uma lista completa de eventos de webhook e quando são executados pode ser encontrada na referência da API de webhooks.
Como nosso webhook está gerenciando problemas em um repositório, clicaremos em Deixe-me selecionar eventos individuais e, em seguida, problemas. Certifique-se de selecionar Ativo para receber eventos de problemas para webhooks acionados. Você também pode selecionar todos os eventos usando a opção-padrão.
Ao terminar, clique em Adicionar webhook. Ufa! Agora que você criou o webhook, é hora de configurar nosso servidor local para testar o webhook. Vá até Configurar seu servidor para aprender como fazê-lo.
Evento curinga
Para configurar um webhook para todos os eventos, use o caractere curinga (*) para especificar os eventos de webhook. Ao adicionar o evento curinga, substituiremos todos os eventos existentes que você tenha configurado pelo evento curinga e enviaremos todas as cargas para os eventos compatíveis. Você também obterá automaticamente todos os novos eventos que possamos adicionar no futuro.