Agora que entendemos os conceitos básicos dos webhooks, vamos ver o processo de criação da nossa integração habilitada para 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, configure quais eventos o webhook deve ouvir. Em seguida, você irá configurar seu servidor para receber e gerenciar a carga.
Você pode usar a API REST para gerenciar o repositório, a organização e os webhooks de aplicativo. Você pode listar entregas de webhook para um webhook ou obter e reenviar uma entrega individual para um webhook, que pode ser integrado a um aplicativo ou serviço externo. Você também pode usar a API REST para alterar a configuração do webhook. Por exemplo, você pode modificar a URL da carga, tipo de conteúdo, verificação de SSL e segredo. Para obter mais informações, consulte:
Expor o host local na internet
Para os propósitos deste tutorial, você usará um servidor local para receber eventos de webhook de GitHub.
Em primeiro lugar, é preciso expor o ambiente de desenvolvimento local à Internet para que o GitHub possa entregar eventos. Use o ngrok para isso.
O ngrok está disponível gratuitamente para todos os principais sistemas operacionais. Para obter mais informações, confira a página de download do ngrok.
Depois de instalar ngrok, você poderá expor o localhost executando ./ngrok http 4567 na linha de comando. 4567 é o número da porta em que o servidor escutará as mensagens. Você deve ver uma linha parecida mais ou menos com isso:
$ Forwarding http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567Anote a URL do *.ngrok.io. Vamos usá-lo para configurar nosso webhook.
Configurando 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. Nela, clique em Webhooks e em Adicionar webhook.
Como alternativa, você pode optar por criar e gerenciar um webhook por meio 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 do conteúdo
Observação: os webhooks do GitHub atualmente não dão suporte ao IPv6, mas irão no futuro. O ponto de extremidade da API REST /meta retorna intervalos IPv6 para habilitar essa transição.
A URL do conteúdo é a URL do servidor que receberá as solicitações POST do webhook.
Como estamos fazendo o desenvolvimento local para nosso tutorial, vamos defini-la como a URL *.ngrok.io, seguido de /payload. Por exemplo, http://7e9ea9dc.ngrok.io/payload.
Tipo de conteúdo
Os webhooks podem ser entregues usando diferentes tipos de conteúdo:
- O tipo de conteúdo
application/jsonfornecerá o conteúdo JSON diretamente como o corpo da solicitaçãoPOST. - O tipo de conteúdo
application/x-www-form-urlencodedenvia o conteúdo JSON como um parâmetro de formulário chamadopayload.
Selecione a mais adequada às suas necessidades. Para este tutorial, o tipo de conteúdo padrão application/json é adequado.
Segredo
A definição de um segredo de webhook permite que você garanta que as solicitações POST enviadas para a URL do conteúdo sejam provenientes do GitHub Enterprise Server. Ao definir um segredo, você receberá os cabeçalhos X-Hub-Signature e X-Hub-Signature-256 na solicitação POST do webhook. Para obter mais informações sobre como usar um segredo com um cabeçalho de assinatura para proteger suas cargas de webhook, confira "Protegendo seus webhooks".
Verificação 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 o 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.
Encontre uma lista completa de eventos de webhook e quando eles podem ser executados na referência da API de webhooks.
Como o webhook está lidando com problemas em um repositório, clicaremos em Deixar-me selecionar eventos individuais e em Problemas. Verifique se você selecionou Ativo para receber eventos de problema para webhooks disparados. Você também pode selecionar todos os eventos usando a opção-padrão.
Quando terminar, clique em Adicionar webhook.
Agora que você criou o webhook, é hora de configurar nosso servidor local para testar o webhook. Acesse Como configurar o servidor para saber como fazer isso.
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.