Assim que seu servidor estiver configurado para receber cargas, ele ouvirá qualquer carga enviada para o ponto de extremidade que você configurou. Por motivos de segurança, você provavelmente vai querer limitar os pedidos para aqueles provenientes do GitHub. Existem algumas maneiras de fazer isso. Você poderia, por exemplo, optar por permitir solicitações do endereço IP do GitHub. No entanto, um método muito mais fácil é configurar um token secreto e validar a informação.
É possível usar o repositório, organização e as APIs REST do webhook do aplicativo para criar, atualizar, excluir e fixar webhooks. Para obter mais informações, consulte:
Definir seu token secreto
Você precisará configurar seu token secreto em dois lugares: no GitHub e no seu servidor.
Para definir seu token no GitHub:
- Navegue até o repositório onde você está configurando seu webhook.
- Preencha a caixa de texto do segredo. Use uma string aleatória com alta entropia (por exemplo, pegando a saída de
ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'no terminal).
- Clique em Atualizar o webhook.
Em seguida, configure uma variável de ambiente em seu servidor que armazene este token. Normalmente, isso é tão simples quanto executar:
$ export SECRET_TOKEN=your_tokenNunca pré-programe o token no seu aplicativo!
Validar cargas do GitHub
Quando seu token secreto está definido, GitHub Enterprise Server o utiliza para criar uma assinatura de hash com cada carga. Esta assinatura hash está incluída com os cabeçalhos de cada solicitação como X-Hub-Signature-256.
Por exemplo, se você tem um servidor básico que ouve webhooks, ele poderá ser configurado de forma semelhante a isso:
require 'sinatra'
require 'json'
post '/payload' do
request.body.rewind
push = JSON.parse(request.body.read)
"I got some JSON: #{push.inspect}"
end
O objetivo é calcular um hash usando seu SECRET_TOKEN e garantir que o resultado corresponda ao hash de GitHub Enterprise Server. GitHub Enterprise Server usa um resumo hexadecimal HMAC para calcular o hash. Portanto, você pode reconfigurar o seu servidor para que se pareça mais ou menos assim:
post '/payload' do
request.body.rewind
payload_body = request.body.read
verify_signature(payload_body)
push = JSON.parse(payload_body)
"I got some JSON: #{push.inspect}"
end
def verify_signature(payload_body)
signature = 'sha1=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), ENV['SECRET_TOKEN'], payload_body)
return halt 500, "Signatures didn't match!" unless Rack::Utils.secure_compare(signature, request.env['HTTP_X_HUB_SIGNATURE'])
end
Observação: As cargas de webhook podem conter caracteres de unicode. Se o seu idioma e a implementação de servidor especificarem uma codificação de caracteres, certifique-se de que você manipula a carga como UTF-8.
A sua linguagem e implementações do servidor podem ser diferentes deste código de exemplo. No entanto, há uma série de aspectos muito importantes a destacar:
-
Não importa qual implementação você usar, a assinatura hash começa com , usando a chave do seu token secreto e o seu texto de carga.
-
Não se recomenda usar um operador simples de
==. Um método comosecure_compareexecuta uma comparação de strings "tempo constante", o que ajuda a mitigar certos ataques de tempo contra operadores de igualdade regular.