bullet_train-outgoing_webhooks 1.24.0 → 1.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f25fee3752c94a0cb76bb8c916f12668510c536b2b2c8f4691d3987550c2ce78
-  data.tar.gz: 9c9af6f83cb45497bfff87a58389028c16203f414c000f9b7ebd6a5a83a824b9
+  metadata.gz: dba0cb965743f696358e08d3f2bcfefbec7598b4de625b3315469d030a2be551
+  data.tar.gz: 9d33299349ba554bb4d409c39c9831cbbdc1355414f621068c623d6734d360e4
 SHA512:
-  metadata.gz: 515e2a9ea6000a18566d87d067fa77b40d549f341ff091313e06b4823caea3221b3d64e8d1e094e667a828a35c88a71804ef5978a2f579b6b53acf92c1756426
-  data.tar.gz: 040f758cb37aa680a2b5d0052a0240ebfda9c0cbbd0aa078d89b8ee87461e7e6cdbc33fbca6ce4eaca5615d4f7b06187788ad8a6112976b41d657f16ef8fe1f7
+  metadata.gz: c7f09f96deff0e056aa9d6e3732e4dba9c407f6c8adbf7ffa627d13f0d94f3e6db4d32a73efd836331b93aed07314f3d7176ff824e0657bc337c522e9dfa6721
+  data.tar.gz: 4e4754e98e1e5003ed4ee4ee656368a08fd27cf0e327f332cf191a36e2b1f9056bb327dd12d23e64bac6d61457f6866cbf02e5bf16b0a6186c2f864fcca67d84

data/app/controllers/account/webhooks/outgoing/endpoints_controller.rb

@@ -60,6 +60,17 @@ class Account::Webhooks::Outgoing::EndpointsController < Account::ApplicationCon
     end
   end
 
+  # POST /account/webhooks/outgoing/endpoints/:id/rotate_secret
+  def rotate_secret
+    @endpoint ||= Webhooks::Outgoing::Endpoint.accessible_by(current_ability).find(params[:id])
+
+    respond_to do |format|
+      if @endpoint.rotate_webhook_secret!
+        format.html { redirect_to [:account, @endpoint], notice: I18n.t("webhooks/outgoing/endpoints.notifications.secret_rotated") }
+      end
+    end
+  end
+
   private
 
   # Never trust parameters from the scary internet, only allow the white list through.

data/app/models/concerns/webhooks/outgoing/delivery_attempt_support.rb

@@ -59,10 +59,22 @@ module Webhooks::Outgoing::DeliveryAttemptSupport
         http.verify_mode = BulletTrain::OutgoingWebhooks.http_verify_mode
       end
     end
+
     request = Net::HTTP::Post.new(uri.request_uri)
     request.add_field("Host", uri.host)
     request.add_field("Content-Type", "application/json")
-    request.body = delivery.event.payload.to_json
+
+    # Generate and add signature headers
+    payload = delivery.event.payload
+    signature_data = BulletTrain::OutgoingWebhooks::Signature
+      .generate(payload, delivery.endpoint.webhook_secret)
+
+    webhook_headers_namespace = Rails.configuration.outgoing_webhooks[:webhook_headers_namespace]
+    request.add_field("#{webhook_headers_namespace}-Signature", signature_data[:signature])
+    request.add_field("#{webhook_headers_namespace}-Timestamp", signature_data[:timestamp])
+    request.add_field("#{webhook_headers_namespace}-Id", delivery.event.uuid)
+
+    request.body = payload.to_json
 
     begin
       response = http.request(request)

data/app/models/concerns/webhooks/outgoing/endpoint_support.rb

@@ -14,8 +14,10 @@ module Webhooks::Outgoing::EndpointSupport
     validates :name, presence: true
 
     before_validation { url&.strip! }
+    before_validation :generate_webhook_secret, on: :create
 
     validates :url, presence: true, allowed_uri: BulletTrain::OutgoingWebhooks.advanced_hostname_security
+    validates :webhook_secret, presence: true
 
     after_initialize do
       self.event_type_ids ||= []
@@ -40,4 +42,12 @@ module Webhooks::Outgoing::EndpointSupport
   def touch_parent
     send(BulletTrain::OutgoingWebhooks.parent_association).touch
   end
+
+  def generate_webhook_secret
+    self.webhook_secret ||= SecureRandom.hex(32)
+  end
+
+  def rotate_webhook_secret!
+    update!(webhook_secret: SecureRandom.hex(32))
+  end
 end

data/app/views/account/webhooks/outgoing/endpoints/_form.html.erb

@@ -14,6 +14,7 @@
     <%# 🚅 super scaffolding will insert new fields above this line. %>
   <% end %>
 
+
   <div class="buttons">
     <%= form.submit (form.object.persisted? ? t('.buttons.update') : t('.buttons.create')), class: "button" %>
     <% if form.object.persisted? %>

data/app/views/account/webhooks/outgoing/endpoints/_index.html.erb

@@ -15,6 +15,7 @@
           <tr>
             <th><%= t('.fields.name.heading') %></th>
             <th><%= t('.fields.url.heading') %></th>
+            <th><%= t('.fields.webhook_secret.heading') %></th>
             <%# 🚅 super scaffolding will insert new field headers above this line. %>
             <th class="text-right"></th>
           </tr>
@@ -25,6 +26,7 @@
               <tr data-id="<%= endpoint.id %>">
                 <td><%= render 'shared/attributes/text', attribute: :name, url: [:account, endpoint] %></td>
                 <td><%= render 'shared/attributes/code', attribute: :url %></td>
+                <td><%= render 'shared/attributes/code', attribute: :webhook_secret, secret: true %></td>
                 <%# 🚅 super scaffolding will insert new fields above this line. %>
                 <td class="buttons">
                   <% unless hide_actions %>

data/app/views/account/webhooks/outgoing/endpoints/show.html.erb

@@ -28,6 +28,7 @@
           <% end %>
 
           <%= render 'shared/attributes/belongs_to', attribute: :scaffolding_absolutely_abstract_creative_concept %>
+          <%= render 'shared/attributes/code', attribute: :webhook_secret, secret: true %>
           <%# 🚅 super scaffolding will insert new fields above this line. %>
         <% end %>
       <% end %>
@@ -36,6 +37,14 @@
         <%= link_to t('.buttons.edit'), [:edit, :account, @endpoint], class: first_button_primary if can? :edit, @endpoint %>
         <%= button_to t('.buttons.destroy'), [:account, @endpoint], method: :delete, class: first_button_primary, data: { turbo_confirm: t('.buttons.confirmations.destroy', model_locales(@endpoint)) } if can? :destroy, @endpoint %>
         <%= link_to t('global.buttons.back'), [:account, @parent, :webhooks_outgoing_endpoints], class: first_button_primary %>
+        <% if can? :edit, @endpoint %>
+          <%=
+            button_to t('.buttons.rotate_secret'),
+              rotate_secret_account_webhooks_outgoing_endpoint_path(@endpoint),
+              method: :post, class: first_button_primary,
+              data: { turbo_confirm: t('.buttons.confirmations.rotate_secret', model_locales(@endpoint)) }
+          %>
+        <% end %>
       <% end %>
     <% end %>
 

data/app/views/api/v1/webhooks/outgoing/endpoints/_endpoint.json.jbuilder

@@ -7,3 +7,8 @@ json.extract! endpoint,
   # 🚅 super scaffolding will insert new fields above this line.
   :created_at,
   :updated_at
+
+# Avoid spilling secrets via the API. We still need to show it once on create so
+# endpoints created programmaticly via the API can save it and use it to verify
+# the signature.
+json.webhook_secret endpoint.webhook_secret if endpoint.previously_new_record?

data/config/locales/en/webhooks/outgoing/endpoints.en.yml

@@ -12,12 +12,15 @@ en:
       edit: Edit Settings
       update: Update Endpoint
       destroy: Remove Endpoint
+      rotate_secret: Rotate Secret
       shorthand:
         edit: Settings
         destroy: Delete
       confirmations:
-        # TODO customize for your use-case.
         destroy: Are you sure you want to remove %{endpoint_name}? This will also remove it's associated data. This can't be undone.
+        rotate_secret: >
+          Are you sure you want to rotate the secret of the endpoint %{endpoint_name}?
+          Your webhook event verification system will need to start handling the new secret.
     fields: &fields
       id:
         _: &id Endpoint ID
@@ -74,6 +77,15 @@ en:
 
       scaffolding_absolutely_abstract_creative_concept: *scaffolding_absolutely_abstract_creative_concept
 
+      webhook_secret:
+        _: &webhook_secret Webhook Secret
+        label: *webhook_secret
+        heading: *webhook_secret
+        api_description: |
+          Each webhook endpoint has a rollable secret. If you create your endpoints programmatically
+          via the API, the secret is only shown after creating the endpoint. If you missed to store
+          it, you will need to look it up on the app's UI endpoint show or index pages.
+        truncation_with_instructions: ... (use button below to rotate)
       # 🚅 super scaffolding will insert new fields above this line.
       created_at:
         _: &created_at Added
@@ -130,6 +142,7 @@ en:
       created: Endpoint was successfully created.
       updated: Endpoint was successfully updated.
       destroyed: Endpoint was successfully destroyed.
+      secret_rotated: Endpoint's webhook secret successfully rotated.
   account:
     webhooks:
       outgoing:
@@ -142,6 +155,7 @@ en:
         api_version: *api_version
         event_type_ids: *event_type_ids
         scaffolding_absolutely_abstract_creative_concept_id: *scaffolding_absolutely_abstract_creative_concept_id
+        webhook_secret: *webhook_secret
         # 🚅 super scaffolding will insert new activerecord attributes above this line.
         created_at: *created_at
-        updated_at: *updated_at
+        updated_at: *updated_at

data/config/routes.rb

@@ -10,6 +10,10 @@ Rails.application.routes.draw do
               resources :deliveries, only: %i[index show] do
                 resources :delivery_attempts, only: %i[index show]
               end
+
+              member do
+                post :rotate_secret
+              end
             end
           end
         end

data/lib/bullet_train/outgoing_webhooks/engine.rb

@@ -22,7 +22,9 @@ module BulletTrain
           allowed_schemes: %w[http https],
           custom_block_callback: nil,
           custom_allow_callback: nil,
-          audit_callback: ->(obj, uri) { Rails.logger.error("BlockedURI obj=#{obj.persisted? ? obj.to_global_id : "New #{obj.class}"} uri=#{uri}") }
+          audit_callback: ->(obj, uri) { Rails.logger.error("BlockedURI obj=#{obj.persisted? ? obj.to_global_id : "New #{obj.class}"} uri=#{uri}") },
+          webhook_headers_namespace: "X-Webhook-Bullet-Train",
+          event_verification_tolerance_seconds: 600 # 5-10 minutes is industry-default.
         }
       end
     end

data/lib/bullet_train/outgoing_webhooks/signature.rb

@@ -0,0 +1,68 @@
+module BulletTrain
+  module OutgoingWebhooks
+    # Provides methods for webhook signatures. This module also serves as an
+    # example that can be used by receiving applications to verify webhook
+    # authenticity.
+    module Signature
+      # Verifies the authenticity of a webhook request.
+      #
+      # @param payload [String] The raw request body as a string.
+      # @param timestamp [String] The timestamp from the Timestamp request header.
+      # @param signature [String] The signature from the Signature request header.
+      # @param secret [String] The webhook secret attached to the endpoint the event comes from.
+      # @return [Boolean] True if the signature is valid, false otherwise.
+      def self.verify(payload, signature, timestamp, secret)
+        return false if payload.blank? || signature.blank? || timestamp.blank? || secret.blank?
+
+        tolerance = Rails.configuration.outgoing_webhooks[:event_verification_tolerance_seconds]
+        # Check if the timestamp is too old
+        timestamp_int = timestamp.to_i
+        now = Time.now.to_i
+
+        if (now - timestamp_int).abs > tolerance
+          return false # Webhook is too old or timestamp is from the future
+        end
+
+        # Compute the expected signature
+        signature_payload = "#{timestamp}.#{payload}"
+        expected_signature = OpenSSL::HMAC.hexdigest("SHA256", secret, signature_payload)
+
+        # Compare signatures using constant-time comparison to prevent timing attacks
+        ActiveSupport::SecurityUtils.secure_compare(expected_signature, signature)
+      end
+
+      # A Rails controller helper example to verify webhook requests.
+      #
+      # @param request [ActionDispatch::Request] The Rails request object.
+      # @param secret [String] The webhook secret shared with the sender.
+      # @return [Boolean] True if the signature is valid, false otherwise.
+      def self.verify_request(request, secret)
+        return false if request.blank? || secret.blank?
+
+        webhook_headers_namespace = Rails.configuration.outgoing_webhooks[:webhook_headers_namespace]
+        signature = request.headers["#{webhook_headers_namespace}-Signature"]
+        timestamp = request.headers["#{webhook_headers_namespace}-Timestamp"]
+        payload = request.raw_post
+
+        return false if signature.blank? || timestamp.blank?
+
+        verify(payload, signature, timestamp, secret)
+      end
+
+      # Algorithm to generate the signature.
+      #
+      # @payload [Hash] The payload to be encoded into a signature.
+      # @secret [String] The secret stored on each webhook endpoint.
+      def self.generate(payload, secret)
+        timestamp = Time.now.to_i.to_s
+        signature_payload = "#{timestamp}.#{payload.to_json}"
+        signature = OpenSSL::HMAC.hexdigest("SHA256", secret, signature_payload)
+
+        {
+          signature: signature,
+          timestamp: timestamp
+        }
+      end
+    end
+  end
+end

data/lib/bullet_train/outgoing_webhooks/version.rb

@@ -1,5 +1,5 @@
 module BulletTrain
   module OutgoingWebhooks
-    VERSION = "1.24.0"
+    VERSION = "1.25.0"
   end
 end

data/lib/bullet_train/outgoing_webhooks.rb

@@ -1,5 +1,6 @@
 require "bullet_train/outgoing_webhooks/version"
 require "bullet_train/outgoing_webhooks/engine"
+require "bullet_train/outgoing_webhooks/signature"
 
 module BulletTrain
   module OutgoingWebhooks

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bullet_train-outgoing_webhooks
 version: !ruby/object:Gem::Version
-  version: 1.24.0
+  version: 1.25.0
 platform: ruby
 authors:
 - Andrew Culver
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -182,6 +196,7 @@ files:
 - db/migrate/20221231003438_remove_default_from_webhooks_outgoing_events.rb
 - lib/bullet_train/outgoing_webhooks.rb
 - lib/bullet_train/outgoing_webhooks/engine.rb
+- lib/bullet_train/outgoing_webhooks/signature.rb
 - lib/bullet_train/outgoing_webhooks/version.rb
 - lib/tasks/bullet_train/outgoing_webhooks_tasks.rake
 homepage: https://github.com/bullet-train-co/bullet_train-core/tree/main/bullet_train-outgoing_webhooks