Melhores práticas para usar webhooks

Você só deve se inscrever nos eventos de webhook de que necessita. Isso reduzirá a quantidade de trabalho que seu servidor precisará executar. Para obter mais informações sobre como assinar eventos, confira Criação de webhooks e Editando webhooks.

Usar um segredo de webhook

Aviso

Para evitar a exposição acidental de informações sensíveis, não inclua informações confidenciais na URL do payload. Isso inclui suas chaves de API e outras credenciais de autenticação. Em vez disso, para validar que as entregas de webhook foram enviadas pelo GitHub e não foram adulteradas, use um segredo de webhook. Para saber mais, confira Validação de entregas de webhooks.

O segredo do webhook deve ser uma sequência de caracteres aleatória com alta entropia. Você deve armazenar com segurança seu segredo de webhook de uma maneira que seu servidor possa acessar.

Usar verificação HTTPS e SSL

Você deve garantir que seu servidor use uma conexão HTTPS. Por padrão, GitHub verificará certificados SSL ao fornecer webhooks. GitHub recomenda que você deixe a verificação SSL habilitada.

Permitir os endereços IP do GitHub

Você pode configurar uma lista de permissões de IP para o servidor e adicionar os endereços IP que GitHub usa para entregas de webhook. Isso pode bloquear solicitações fraudulentas para o servidor.

Você pode usar o GET /meta endpoint para localizar a lista atual de GitHub endereços IP. Para saber mais, confira Pontos de extremidade da API REST para metadados. GitHub ocasionalmente, faz alterações em seus endereços IP, portanto, você deve atualizar sua lista de permissões de IP periodicamente.

Para saber mais, confira Sobre os endereços IP do GitHub.

Responder dentro de 10 segundos

Seu servidor deve responder com resposta 2XX dentro de 10-30 segundos após receber um envio de webhook. Se o servidor demorar mais do que isso para responder, encerrará GitHub a conexão e considerará a entrega uma falha.

Para responder em tempo hábil, convém configurar uma fila para processar conteúdo de webhook de forma assíncrona. Seu servidor pode responder ao receber o webhook e, em seguida, processar o conteúdo em segundo plano sem bloquear futuras entregas de webhook. Por exemplo, você pode usar serviços como Hookdeck ou bibliotecas como Resque (Ruby), < RQ (Python) ou RabbitMQ (Java).

Verifique o tipo de evento e a ação antes de processar o evento

Há vários tipos de evento de webhook e muitos eventos podem ter vários tipos de ação. GitHub continua a adicionar novos tipos de eventos e novas ações aos tipos de eventos existentes. Seu aplicativo deve verificar o tipo de evento e a ação de um conteúdo de webhook antes de processar o conteúdo. Para determinar o tipo de evento, você pode usar o cabeçalho de solicitação X-GitHub-Event. Para determinar o tipo de ação, você pode usar a chave action de nível superior no conteúdo do evento.

Reentregar entregas perdidas

Se o servidor ficar inoperante, você deverá reenviar os webhooks perdidos assim que o servidor voltar a funcionar. Para saber mais, confira Entregar webhooks novamente.

Usar o cabeçalho `X-GitHub-Delivery`

Em um ataque de reprodução, um agente mal-intencionado intercepta uma entrega de webhook e reenvia a entrega. Para proteção contra ataques de repetição, você pode usar o cabeçalho X-GitHub-Delivery para garantir que cada entrega seja única por evento.

Observação

Se você solicitar uma reentrega, o cabeçalho X-GitHub-Delivery será o mesmo que na entrega original.

Leitura adicional

        [AUTOTITLE](/rest/guides/best-practices-for-integrators)

        [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app)

Melhores práticas para usar webhooks

Neste artigo