fix: add documentation and fix typos #13903

app/controllers/api/v1/webhooks_controller.rb

@@ -4,56 +4,65 @@ module Api
   module V1
     # Recibe webhooks y lanza un PullJob
     class WebhooksController < BaseController
+      # responde con forbidden si falla la validación del token
       rescue_from ActiveRecord::RecordNotFound, with: :platforms_answer
 
       # Trae los cambios a partir de un post de Webhooks:
-        # (Gitlab, Github, Guitea, etc)
+      # (Gitlab, Github, Gitea, etc)
       def pull 
         message = I18n.with_locale(site.default_locale) do
           I18n.t('webhooks.pull.message')
         end
 
         GitPullJob.perform_later(site, usuarie, message)
-          platforms_answer
+        head :ok
       end
 
       private 
 
+      # encuentra el sitio a partir de la url
       def site 
         @site ||= Site.find_by_name!(params[:site_id])
       end
 
       # valida el token que envía la plataforma del webhook
+      #
+      # @return [String]
       def token 
         @token ||=
           begin
             # Gitlab
             if request.headers['X-Gitlab-Token']
-                request.headers["X-Gitlab-Token"]
+              request.headers['X-Gitlab-Token']
             # Github
             elsif request.headers['X-HUB-SIGNATURE-256']
-                signature(request.env['HTTP_X_HUB_SIGNATURE_256'])
-              # Guitea
+              request.env['HTTP_X_HUB_SIGNATURE_256']
+            # Gitea
             else
-                signature(request.env['HTTP_X_GITEA_SIGNATURE'])
+              request.env['HTTP_X_GITEA_SIGNATURE']
             end
           end 
       end
 
+      # valida token a partir de firma de webhook
+      #
+      # @return [String]
       def token_from_signature(signature)
         payload = request.body.read  
         site.roles.where(temporal: false, rol: 'usuarie').pluck(:token).find do |token|
-            new_signature = hash_mac(OpenSSL::Digest.new('sha256'), token, payload)
-            @token ||= Rack::Utils.secure_compare(new_signature, signature)
+          new_signature = 'sha256=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), token, payload)
+          ActiveSupport::SecurityUtils.secure_compare(new_signature, signature)
         end
       end
 
+      # encuentra le usuarie 
       def usuarie
-          @usuarie = site.roles.find_by!(temporal: false, rol: 'usuarie', token: token).usuarie
+        @usuarie ||= site.roles.find_by!(temporal: false, rol: 'usuarie', token: token).usuarie
       end        
 
+      # respuesta de error a plataformas
       def platforms_answer
-          head :ok
+        head :forbidden
       end
     end
   end

config/locales/es.yml

@@ -476,7 +476,7 @@ es:
         message: 'Actualización del esqueleto'
   webhooks_controller:
     pull:
-      message: 'Pull de webhooks'
+      message: 'Traer los cambios a partir de un evento remoto'
   footer:
     powered_by: 'es desarrollada por'
   i18n: