Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais recentes, acesse a documentação em inglês. Se houver problemas com a tradução desta página, entre em contato conosco.

Criar webhooks

Aprenda a criar um webhook, escolhendo os eventos que seu webhook irá ouvir em GitHub e como configurar um servidor para receber e gerenciar a carga de webhook.

Neste artigo

Now that we understand the basics of webhooks, let's go through the process of building out our own webhook-powered integration. In this tutorial, we'll create a repository webhook that will be responsible for listing out how popular our repository is, based on the number of issues it receives per day.

Criar um webhook é um processo de duas etapas. You'll first need to set up how you want your webhook to behave through GitHub: what events should it listen to. Em seguida, você irá configurar seu servidor para receber e gerenciar a carga.

É possível usar o repositório, organização e as APIs REST do webhook do aplicativo para criar, atualizar, excluir e fixar webhooks. You can also use the REST API to change the configuration of the 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:

Exposing localhost to the internet

For the purposes of this tutorial, we're going to use a local server to receive messages from GitHub. So, first of all, we need to expose our local development environment to the internet. We'll use ngrok to do this. ngrok is available, free of charge, for all major operating systems. For more information, see the ngrok download page.

After installing ngrok, you can expose your localhost by running ./ngrok http 4567 on the command line. 4567 is the port number on which our server will listen for messages. Você deve ver uma linha parecida mais ou menos com isso:

$ Forwarding    http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567

Make a note of the *.ngrok.io URL. We'll use it to set up our webhook.

Setting up a 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.

Since we're developing locally for our tutorial, we'll set it to the *.ngrok.io URL, followed by /payload. For example, 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 de application/json fornecerá a carga do JSON diretamente como o texto da solicitação POST.
  • O tipo de conteúdo application/x-www-form-urlencoded enviará a carga do JSON como um parâmetro de formulário denominado carga.

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. When you set a secret, you'll receive the X-Hub-Signature and X-Hub-Signature-256 headers 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."

SSL verification

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.

Since our webhook is dealing with issues in a repository, we'll click Let me select individual events and then Issues. 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.

Now that you've created the webhook, it's time to set up our local server to test the webhook. Vá até Configurar seu servidor para aprender como fazê-lo.

Wildcard event

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.

Esse documento ajudou você?

Privacy policy

Ajude-nos a tornar esses documentos ótimos!

Todos os documentos do GitHub são de código aberto. Você percebeu que algo que está errado ou não está claro? Envie um pull request.

Faça uma contribuição

Ou, aprenda como contribuir.