Add webhook signature verification example coming from a Bullet Train app

First we super-scaffolded a new incoming webhooks controller `rails g super_scaffold:incoming_webhooks BulletTrain`.

Then, the `verify` and `verify_request` methods were taken from the Bullet Train repo to verify the signature in the controller. If a signature is not verified, we don't save a new Webhook record to the DB.

Author: RichStone

app/controllers/webhooks/incoming/bullet_train_webhooks_controller.rb

@@ -0,0 +1,16 @@
+class Webhooks::Incoming::BulletTrainWebhooksController < Webhooks::Incoming::WebhooksController
+  before_action :verify_authenticity, only: [:create]
+
+  def create
+    Webhooks::Incoming::BulletTrainWebhook.create(data: JSON.parse(request.raw_post)).process_async
+    render json: {status: "OK"}, status: :created
+  end
+
+  private
+
+  def verify_authenticity
+    unless Webhooks::Incoming::Signature.verify_request(request, ENV["BULLET_TRAIN_WEBHOOK_SECRET"])
+      render json: {error: "Signature verification failed"}, status: :forbidden
+    end
+  end
+end

app/models/webhooks/incoming/bullet_train_webhook.rb

@@ -0,0 +1,11 @@
+class Webhooks::Incoming::BulletTrainWebhook < BulletTrain::Configuration.incoming_webhooks_parent_class_name.constantize
+  include Webhooks::Incoming::Webhook
+
+  def verify_authenticity
+    # Signature is verified in the controller.
+    true
+  end
+
+  def process
+  end
+end

app/models/webhooks/incoming/signature.rb

@@ -0,0 +1,47 @@
+# A usage example of using Bullet Train's webhook signature verification
+# methods.
+class Webhooks::Incoming::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_seconds = 300
+    # Check if the timestamp is too old
+    timestamp_int = timestamp.to_i
+    now = Time.now.to_i
+
+    if (now - timestamp_int).abs > tolerance_seconds
+      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?
+
+    signature = request.headers["X-Webhook-Bullet-Train-Signature"]
+    timestamp = request.headers["X-Webhook-Bullet-Train-Timestamp"]
+    payload = request.raw_post
+
+    return false if signature.blank? || timestamp.blank?
+
+    verify(payload, signature, timestamp, secret)
+  end
+end

config/routes.rb

@@ -27,6 +27,7 @@
 
   namespace :webhooks do
     namespace :incoming do
+      resources :bullet_train_webhooks
       resources :click_funnels_webhooks, only: [:create]
       namespace :oauth do
         # 🚅 super scaffolding will insert new oauth provider webhooks above this line.

test/controllers/webhooks/incoming/bullet_train_webhooks_controller_test.rb

@@ -0,0 +1,80 @@
+require "test_helper"
+
+class Webhooks::Incoming::BulletTrainWebhooksControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    @user = FactoryBot.create(:onboarded_user)
+    @membership = @user.memberships.first
+    @team = @user.current_team
+
+    @original_webhook_secret = ENV["BULLET_TRAIN_WEBHOOK_SECRET"]
+    ENV["BULLET_TRAIN_WEBHOOK_SECRET"] = "test_webhook_secret"
+  end
+
+  teardown do
+    ENV["BULLET_TRAIN_WEBHOOK_SECRET"] = @original_webhook_secret
+  end
+
+  test "should process incoming webhook with valid signature" do
+    json_payload = sample_webhook_payload
+    timestamp = Time.now.to_i.to_s
+    signature = generate_signature(json_payload, timestamp)
+
+    post "/webhooks/incoming/bullet_train_webhooks",
+      params: json_payload,
+      headers: {
+        "X-Webhook-Bullet-Train-Signature" => signature,
+        "X-Webhook-Bullet-Train-Timestamp" => timestamp,
+        "Content-Type" => "application/json"
+      }
+
+    assert_response :created
+    assert_equal({"status" => "OK"}, response.parsed_body)
+
+    webhook = Webhooks::Incoming::BulletTrainWebhook.first
+    assert_equal JSON.parse(json_payload), webhook.data
+  end
+
+  test "should reject incoming webhook with invalid signature" do
+    json_payload = sample_webhook_payload
+    timestamp = Time.now.to_i.to_s
+    invalid_signature = "invalid_signature_here"
+
+    post "/webhooks/incoming/bullet_train_webhooks",
+      params: json_payload,
+      headers: {
+        "X-Webhook-Bullet-Train-Signature" => invalid_signature,
+        "X-Webhook-Bullet-Train-Timestamp" => timestamp,
+        "Content-Type" => "application/json"
+      }
+
+    assert_response :forbidden
+    assert_equal({"error" => "Signature verification failed"}, response.parsed_body)
+
+    # Verify no webhook was created
+    assert_equal 0, Webhooks::Incoming::BulletTrainWebhook.count
+  end
+
+  private
+
+  def sample_webhook_payload
+    '{
+      "data": {
+        "id": 4,
+        "name": "aaa",
+        "team_id": 3,
+        "created_at": "2025-06-05T09:27:41.939Z",
+        "updated_at": "2025-06-05T09:27:41.939Z",
+        "description": ""
+      },
+      "event_id": "9abb8b6e49e5e7ffab7212bce01a7f97",
+      "event_type": "scaffolding/absolutely_abstract/creative_concept.created",
+      "subject_id": 4,
+      "subject_type": "Scaffolding::AbsolutelyAbstract::CreativeConcept"
+    }'
+  end
+
+  def generate_signature(payload, timestamp)
+    signature_payload = "#{timestamp}.#{payload}"
+    OpenSSL::HMAC.hexdigest("SHA256", ENV["BULLET_TRAIN_WEBHOOK_SECRET"], signature_payload)
+  end
+end