Como Criar um GitHub App (e o que Colocar no Campo Webhook URL)
Para criar um GitHub App, você o registra em Settings → Developer settings → GitHub Apps — e o formulário de registro pede uma coisa que a maioria das pessoas ainda não tem: uma Webhook URL. O campo é obrigatório sempre que o checkbox "Active" estiver marcado, e ele vem marcado por padrão.
A solução leva uns 30 segundos: abra o webhookbox.net, copie a URL de webhook que ele gera para você na hora (sem cadastro) e cole no formulário. O app é registrado sem travas, cada evento que o GitHub enviar fica capturado e inspecionável, e quando o seu servidor de verdade ficar pronto você encaminha ou reenvia tudo para ele. Este guia percorre o registro inteiro, campo a campo.
O que é um GitHub App (e quando você precisa de um)
GitHub App é a forma de primeira classe de construir uma integração com o GitHub. Diferente de um personal access token (amarrado à conta de um funcionário) ou de um OAuth App (que age em nome de quem o autorizou), um GitHub App tem identidade própria: ele é instalado numa organização ou em repositórios específicos, recebe permissões granulares (por exemplo, "ler issues, escrever pull requests, e nada mais"), autentica com tokens de instalação de curta duração e — a parte que interessa a este guia — pode receber webhooks dos eventos que assinar.
Por isso, conectar uma ferramenta ao GitHub de uma empresa quase sempre significa criar um GitHub App na organização: bots de CI, assistentes de code review, triagem de issues, ferramentas de deploy e dashboards internos seguem esse modelo. A própria documentação do GitHub recomenda GitHub Apps em vez de OAuth Apps para integrações novas.
Passo 1 — Consiga a URL de webhook primeiro (30 segundos, sem cadastro)
- Abra o webhookbox.net. Uma caixa de captura única é criada para você na hora — sem conta, sem cartão.
- Você recebe dois endpoints reais: um de Development e um de Production, no formato
https://hooks.webhookbox.net/ep_…. - Copie a URL de Production — é ela que entra no formulário do GitHub no próximo passo.
Quanto tempo ela dura? Uma caixa anônima vive 7 dias (ou 500 requests). Criando uma conta grátis, a mesma URL vira permanente — o resgate preserva todo o histórico capturado e nada precisa mudar do lado do GitHub. Veja planos e limites.
Passo 2 — Crie o GitHub App, campo a campo
Abra o formulário de registro
Para uma conta pessoal: clique na sua foto de perfil → Settings → Developer settings → GitHub Apps → New GitHub App.
Para uma organização (o caso comum em integrações de empresa): foto de perfil → Your organizations → Settings ao lado da organização → Developer settings → GitHub Apps → New GitHub App. Registrar na organização mantém a propriedade com a empresa, e não com um funcionário — a navegação completa está na documentação de registro do GitHub.
Nome, descrição e Homepage URL
- GitHub App name — obrigatório, até 34 caracteres, único no GitHub inteiro. Na exibição ele vira minúsculas com espaços trocados por hífens.
- Description — opcional; aparece para quem for instalar o app.
- Homepage URL — obrigatória, mas sem drama: o site da empresa ou até a URL do repositório do projeto servem.
Identificação e autorização de usuários (opcional)
A Callback URL — na seção "Identifying and authorizing users" do formulário — só importa se pessoas forem fazer login através do seu app (o fluxo OAuth de autorização de usuário). Para uma integração servidor-a-servidor que reage a eventos, deixe em branco. Mantenha o "Expire user authorization tokens" marcado — é a recomendação do GitHub. O mesmo vale para a Setup URL da seção "Post installation": pule, a menos que precise redirecionar o usuário após a instalação.
Webhook — Active, Webhook URL e Secret
Esta é a seção que trava a maioria dos registros. Mantenha o Active marcado — sua integração existe para receber eventos — e cole no campo Webhook URL a URL do WebhookBox copiada no Passo 1:
O Webhook secret é opcional — uma camada extra de segurança, recomendada quando você for para produção. O GitHub o usa para assinar cada entrega (o header X-Hub-Signature-256) — é assim que o seu servidor consegue verificar que a requisição veio mesmo do GitHub. Se quiser um, gere um valor de alta entropia:
openssl rand -hex 32Se definir um, guarde-o no seu gerenciador de senhas — depois você configura o mesmo valor no lado receptor. O WebhookBox reconhece o esquema de assinatura do GitHub e consegue verificar cada entrega contra o seu secret, ou seja: dá para confirmar que as assinaturas batem antes de escrever uma linha de código de servidor.
Permissões (Permissions)
Conceda o mínimo necessário — as permissões definem o que o app pode tocar, e quem instala vê a lista. Metadata: Read-only entra automaticamente. Um bot de triagem de issues, por exemplo, precisa de Issues: Read & write e de mais nada. Dá para adicionar permissões depois (as instalações existentes precisam aprovar a mudança).
Eventos para assinar (Subscribe to events)
A lista de eventos depende das permissões concedidas: marque os que a sua integração usa (por exemplo Issues, Pull request, Push). Sem permissões extras, você ainda verá Installation target, Meta e Security advisory disponíveis.
Onde este GitHub App pode ser instalado?
Only on this account (o padrão) é o certo para ferramenta interna da empresa. Escolha Any account apenas se outros usuários ou organizações forem instalar o app. Clique em Create GitHub App — pronto. Na tela seguinte, anote o App ID e gere uma private key (um arquivo .pem): você vai precisar dos dois para autenticar chamadas de API.
Passo 3 — Instale o app e veja os eventos chegando
Um GitHub App não faz nada até ser instalado. Na página de configurações do app, abra Install App na barra lateral, escolha a organização e depois All repositories ou uma lista de repositórios.
No instante da instalação, o GitHub envia a primeira entrega: um evento installation (webhooks de repositório mandam um ping; GitHub Apps mandam installation). Volte para a aba do WebhookBox — a requisição já está lá:
Abra a requisição para inspecionar os headers que importam — X-GitHub-Event (o tipo do evento), X-GitHub-Delivery (o id único da entrega) e X-Hub-Signature-256 (a assinatura HMAC) — e o payload JSON completo em árvore navegável. Agora dispare um evento de verdade: abra uma issue ou faça um push num repositório instalado e veja chegar. É o jeito mais rápido de aprender o formato exato do payload que você vai programar contra.
Do lado do GitHub, a aba Advanced do app lista as entregas recentes com o código de resposta — e um botão Redeliver, útil quando o seu endpoint definitivo assumir.
Quando o seu servidor ficar pronto
Há dois caminhos limpos para sair do arranjo temporário — e nenhum perde dados:
- Trocar a URL. Edite o GitHub App e substitua a Webhook URL pelo seu endpoint de produção. Tudo o que foi capturado durante o desenvolvimento continua no WebhookBox, e você pode reenviar em lote para o novo destino — seu servidor processa o backlog também.
- Manter a caixa na frente. Deixe o GitHub App apontando para o WebhookBox e ligue o encaminhamento (forwarding) para o seu servidor — retentativas automáticas com backoff e visibilidade de cada entrega. Você ganha um registro permanente de todos os eventos, replay sob demanda — e nunca mais toca nas configurações do GitHub App. O emissor é configurado uma vez, para sempre.
Esse segundo caminho é o superpoder discreto de começar com uma caixa de captura: a integração já recebia, armazenava e verificava eventos desde o primeiro minuto — antes de o servidor existir — e entrar em produção foi um botão que você ligou do seu lado, sem tocar no GitHub. Destrinchamos esse padrão — e por que vale mantê-lo em produção — em como receber webhooks instantaneamente.
Perguntas frequentes
A Webhook URL é obrigatória ao criar um GitHub App?
Sim, sempre que o checkbox "Active" da seção Webhook estiver marcado — e ele vem marcado por padrão. Se você desmarcar, o app é registrado sem URL, mas não recebe evento nenhum, o que anula o propósito da maioria das integrações. A saída prática é colar uma URL de captura (por exemplo, um endpoint grátis do WebhookBox) e apontar para o seu servidor real depois.
Posso trocar a Webhook URL depois de criar o GitHub App?
Pode. Abra o app em Settings → Developer settings → GitHub Apps → Edit, altere a Webhook URL e salve. Detalhe: as entregas antigas não são reenviadas sozinhas — dá para reentregar uma a uma na aba Advanced, ou, se a URL antiga era uma caixa de captura como o WebhookBox, reenviar em lote tudo o que foi capturado para o novo destino.
Qual a diferença entre GitHub App e OAuth App?
Um GitHub App tem identidade própria, permissões granulares por repositório, webhooks nativos e tokens de instalação de curta duração. Um OAuth App age como o usuário que o autorizou, com escopos mais amplos. O GitHub recomenda GitHub Apps para integrações novas, principalmente em organizações.
Quanto tempo dura a URL grátis do WebhookBox?
Sem conta, a caixa de captura vive 7 dias ou 500 requests, o que vier primeiro. Criando uma conta grátis, a mesma URL passa a ser permanente — sem reconfigurar nada no GitHub — com 1 endpoint, 5.000 requests armazenados e retenção de 7 dias no plano Free; os planos pagos ampliam esses limites.
O WebhookBox verifica a assinatura dos webhooks do GitHub?
Sim. O GitHub assina cada entrega com o header X-Hub-Signature-256 (HMAC do payload usando o seu webhook secret). O WebhookBox reconhece entregas do GitHub, exibe os headers de assinatura e consegue verificar cada entrega contra o secret que você configurar.