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 - quais eventos devem ser ouvidos. Em seguida, você irá configurar seu servidor para receber e gerenciar a carga.
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
The payload URL is the URL of the server that will receive the webhook POST requests.
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
Webhooks can be delivered using different content types:
- The
application/jsoncontent type will deliver the JSON payload directly as the body of thePOSTrequest. - The
application/x-www-form-urlencodedcontent type will send the JSON payload as a form parameter calledpayload.
Choose the one that best fits your needs. Para este tutorial, o tipo de conteúdo-padrão para application/json está certo.
Segredo
Setting a webhook secret allows you to ensure that POST requests sent to the payload URL are from GitHub. When you set a secret, you'll receive the X-Hub-Signature header in the webhook POST request. For more details on how to use the secret and the X-Hub-Signature header to secure your webhook payloads, see "Securing your webhooks."
Verificação de SSL
If your "Payload URL" is a secure site (HTTPS), you will have the option to configure the SSL verification settings. If your "Payload URL" is not secure (HTTP), GitHub will not display this option. By default, GitHub verifies the SSL certificate of your website when delivering webhook payloads. SSL verification helps ensure that hook payloads are delivered to your URL endpoint securely. You have the option to disable SSL, but we recommend keeping Enable SSL verification selected.
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.